diff --git a/site/src/content/docs/versions/reference.md b/site/src/content/docs/versions/reference.md index c8b1170..c025777 100644 --- a/site/src/content/docs/versions/reference.md +++ b/site/src/content/docs/versions/reference.md @@ -45,6 +45,7 @@ description: Every kind of entry versions.yaml takes, the build arguments each b | `today` | today's date | | `with ` | ``'s version, spelled with a `v` only when this entry's is: two files of one release, such as VictoriaMetrics and its vmutils. A bump of `` moves this entry in the same file, and the gate fails while they differ | | `with pin` | ``'s pin: a file named by another's commit, such as the VS Code server of a VS Code release | +| `with [pin]` | the same, of `` in that GitHub repository's `versions.yaml` as its default branch has it now, read through the API (`GITHUB_TOKEN` or `GH_TOKEN` for a private one): `check` says when it moved, and a bump takes it. The gate reads no network, so it does not hold this one | | `follows ` | another entry's, by a relation the file cannot compute, or another repository's: `check` reports it for a person to read | The format only grows. Every repository that uses go-tools reads the same file format, so a field, @@ -89,3 +90,8 @@ lists: adding one is an edit, not a bump. victoriametrics' version and refuses any other. The entry named is one with a track of its own: a chain of `with` is refused as the file is read, and so is one whose entry is not in it. An entry with an `archive` is bumped by hand, so it refuses the bump of the entry it is with. + +An entry can be with another repository's: spin-ami rebuilds the Grafana spin lays, at the tag spin +pins, so its entry is `with spin-stack/spin grafana`. When spin moves Grafana, spin-ami's +`versions check` says its own is behind, and `versions bump grafana` takes the version spin's file +has, spelled as spin-ami's entry spells its own. diff --git a/versions/gate/gate.go b/versions/gate/gate.go index 961cccf..9ab92dd 100644 --- a/versions/gate/gate.go +++ b/versions/gate/gate.go @@ -81,16 +81,7 @@ func (g Gate) Check() error { } // An entry tracked with another is at what that one is at: a bump moves both, and a hand that // moved one alone has written a build of two releases. - for _, e := range v.Entries { - leader, _, ok := e.With() - if !ok { - continue - } - if want, _ := v.Expected(e); e.Version != want { - errs = append(errs, fmt.Errorf("%s: %s is with %s, so it is at %q, not %q: versions bump %s moves both", - versions.File, e.Name, leader, want, e.Version, leader)) - } - } + errs = append(errs, apart(v)...) used := map[string]bool{} for _, rel := range slices.Sorted(maps.Keys(files)) { // A test's digests are fixtures, but what it reads of versions.yaml is read. @@ -118,6 +109,23 @@ func (g Gate) Check() error { return errors.Join(errs...) } +// apart is each entry tracked with another in the file that is not at that one's version. One with +// another repository's entry is check's: the gate reaches nothing over the network. +func apart(v *versions.Versions) []error { + var errs []error + for _, e := range v.Entries { + a, ok, _ := e.With() + if !ok || a.Repo != "" { + continue + } + if want, _ := v.Expected(e); e.Version != want { + errs = append(errs, fmt.Errorf("%s: %s is with %s, so it is at %q, not %q: versions bump %s moves both", + versions.File, e.Name, a.Name, want, e.Version, a.Name)) + } + } + return errs +} + // TaskCommand is the go-tools command a go.mod takes as `go tool task`: Task at versions.yaml's // `task`, with go-tools' latest release on its PATH. const TaskCommand = "github.com/spin-stack/go-tools/cmd/task" diff --git a/versions/gate/gate_test.go b/versions/gate/gate_test.go index fc802b2..3ade9a8 100644 --- a/versions/gate/gate_test.go +++ b/versions/gate/gate_test.go @@ -81,6 +81,10 @@ func TestTheGateSaysWhereAPinIsNotVersionsYAMLs(t *testing.T) { f[versions.File] += "- name: headers\n kind: download\n source: https://y/{version}\n version: v1\n pin: " + strings.Repeat("d", 64) + "\n track: with kernel\n" f["Taskfile.yml"] += " - versions args headers\n" }}, + {name: "an entry tracked with another repository's, which is check's to read", change: func(f map[string]string) { + f[versions.File] += "- name: headers\n kind: download\n source: https://y/{version}\n version: '9'\n pin: " + strings.Repeat("d", 64) + "\n track: with spin-stack/spin kernel\n" + f["Taskfile.yml"] += " - versions args headers\n" + }}, {name: "an entry tracked with another, moved alone", change: func(f map[string]string) { f[versions.File] += "- name: headers\n kind: download\n source: https://y/{version}\n version: '2'\n pin: " + strings.Repeat("d", 64) + "\n track: with kernel\n" f["Taskfile.yml"] += " - versions args headers\n" diff --git a/versions/upstream/upstream.go b/versions/upstream/upstream.go index 5ed792c..1d09dcb 100644 --- a/versions/upstream/upstream.go +++ b/versions/upstream/upstream.go @@ -8,6 +8,7 @@ import ( "bufio" "context" "crypto/sha256" + "encoding/base64" "encoding/hex" "encoding/json" "errors" @@ -92,7 +93,7 @@ func newest(ctx context.Context, v *versions.Versions, e versions.Entry) (string case "follows": return "", fmt.Errorf("%w: %s", errFollows, arg) case "with": - return v.Expected(e) + return newestWith(ctx, v, e) } return "", fmt.Errorf("versions: %s tracks %q, which check does not know", e.Name, e.Track) } @@ -153,10 +154,17 @@ func Bump(ctx context.Context, v *versions.Versions, name, version string) (vers return versions.Entry{}, nil, fmt.Errorf("versions: %s's archive is what a build's git writes of the commit, so it is bumped by hand: see its note", a.Name) } } - if leader, _, ok := e.With(); ok && version != "" { - // Parse refused a with that names no entry, so the expected version is always there. - if want, _ := v.Expected(e); version != want { - return versions.Entry{}, nil, fmt.Errorf("versions: %s is with %s, at %q: bump %s", name, leader, want, leader) + if a, ok, _ := e.With(); ok && version != "" { + want, err := newest(ctx, v, e) + if err != nil { + return versions.Entry{}, nil, err + } + switch { + case version == want: + case a.Repo != "": + return versions.Entry{}, nil, fmt.Errorf("versions: %s is with %s's %s, at %q: it moves when that one does", name, a.Repo, a.Name, want) + default: + return versions.Entry{}, nil, fmt.Errorf("versions: %s is with %s, at %q: bump %s", name, a.Name, want, a.Name) } } if version == "" { @@ -318,6 +326,48 @@ func run(ctx context.Context, name string, args ...string) (string, error) { return string(out), nil } +// newestWith is what an entry tracked with another is at: that one's, in v or in its repository's +// file as it is now. +func newestWith(ctx context.Context, v *versions.Versions, e versions.Entry) (string, error) { + a, _, err := e.With() + switch { + case err != nil: // mutate-exempt: Parse refused a with track of no form, and v is parsed + return "", err + case a.Repo == "": + return v.Expected(e) + } + other, err := repositoryFile(ctx, a.Repo) + if err != nil { + return "", err + } + return versions.ExpectedIn(e, other) +} + +// repositoryFile is the versions.yaml at the default branch of a GitHub repository, owner/repo, +// read through the API so that GITHUB_TOKEN or GH_TOKEN reaches a private one: what that +// repository pins now, which a release of it made later will carry. +func repositoryFile(ctx context.Context, repo string) (*versions.Versions, error) { + var file struct { + Content string `json:"content"` + Encoding string `json:"encoding"` + } + if err := getJSON(ctx, "https://api.github.com/repos/"+repo+"/contents/"+versions.File, &file); err != nil { + return nil, fmt.Errorf("%w (a private repository is read with GITHUB_TOKEN or GH_TOKEN)", err) + } + if file.Encoding != "base64" { + return nil, fmt.Errorf("versions: %s's %s came as %q, not base64", repo, versions.File, file.Encoding) + } + raw, err := base64.StdEncoding.DecodeString(strings.ReplaceAll(file.Content, "\n", "")) + if err != nil { + return nil, fmt.Errorf("versions: %s's %s: %w", repo, versions.File, err) + } + v, err := versions.Parse(raw) + if err != nil { + return nil, fmt.Errorf("%s's %w", repo, err) + } + return v, nil +} + func getJSON(ctx context.Context, url string, into any) error { // Decoded whole once it has all arrived, so an attempt cut short leaves nothing in into. var raw json.RawMessage diff --git a/versions/upstream/upstream_test.go b/versions/upstream/upstream_test.go index 59c3010..3f27aa0 100644 --- a/versions/upstream/upstream_test.go +++ b/versions/upstream/upstream_test.go @@ -3,6 +3,7 @@ package upstream import ( "context" "crypto/sha256" + "encoding/base64" "encoding/hex" "errors" "io" @@ -469,6 +470,9 @@ func TestAnEntryWithAnotherIsBumpedToItsVersion(t *testing.T) { e, _, err := Bump(t.Context(), v, "utils", "") require.NoError(t, err) assert.Equal(t, [2]string{"1.0", sumOf("utils 1")}, [2]string{e.Version, e.Pin}) + e, _, err = Bump(t.Context(), v, "utils", "1.0") + require.NoError(t, err, "named at the version it is with") + assert.Equal(t, sumOf("utils 1"), e.Pin) _, _, err = Bump(t.Context(), v, "utils", "2.0") assert.ErrorContains(t, err, `utils is with lead, at "1.0": bump lead`) } @@ -489,3 +493,77 @@ func TestAnEntryWithAnArchiveStopsItsLeadersBump(t *testing.T) { _, _, err = Bump(t.Context(), v, "lead", "v2.0") assert.ErrorContains(t, err, "src's archive is what a build's git writes") } + +// contents is what GitHub's contents API answers for a file: its bytes in base64, wrapped as the +// API wraps them. +func contents(file string) string { + b64 := base64.StdEncoding.EncodeToString([]byte(file)) + return `{"encoding":"base64","content":"` + b64[:10] + `\n` + b64[10:] + `"}` +} + +const spinFile = `- name: grafana + kind: download + source: https://example.test/grafana-{version}.tgz + version: 13.4.0 + pin: ` + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + ` + track: github-release https://github.com/grafana/grafana +- name: day + kind: date + version: 20260101T000000Z + track: today +` + +const withSpin = `- name: grafana + kind: download + source: https://example.test/g-{version} + version: v13.3.0 + pin: ` + "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + ` + track: with spin-stack/spin grafana +` + +// An entry with another repository's is at what that repository's versions.yaml says now, read +// through GitHub's API: check says it is behind, a bump takes it, and another version is refused. +func TestAnEntryWithAnotherRepositorysMovesWithIt(t *testing.T) { + serve(t, map[string]string{ + "https://api.github.com/repos/spin-stack/spin/contents/versions.yaml": contents(spinFile), + "https://example.test/g-v13.4.0": "grafana 13.4", + }) + v, err := versions.Parse([]byte(withSpin)) + require.NoError(t, err) + st := Check(t.Context(), v) + require.Len(t, st, 1) + assert.Equal(t, "v13.4.0", st[0].Newest) + assert.True(t, st[0].Behind, st[0].Note) + + e, _, err := Bump(t.Context(), v, "grafana", "") + require.NoError(t, err) + assert.Equal(t, [2]string{"v13.4.0", sumOf("grafana 13.4")}, [2]string{e.Version, e.Pin}) + _, _, err = Bump(t.Context(), v, "grafana", "v13.5.0") + assert.ErrorContains(t, err, `grafana is with spin-stack/spin's grafana, at "v13.4.0": it moves when that one does`) +} + +// Another repository's file that cannot be read, or read as one, or that lacks what the entry +// takes of it, is an error that says which: never a version. +func TestAnotherRepositorysFileIsReadOrRefused(t *testing.T) { + api := "https://api.github.com/repos/spin-stack/spin/contents/versions.yaml" + for _, tc := range []struct{ name, answer, track, want string }{ + {"not there, or private with no token", "", "with spin-stack/spin grafana", "GITHUB_TOKEN or GH_TOKEN"}, + {"not base64", `{"encoding":"none","content":""}`, "with spin-stack/spin grafana", `came as "none", not base64`}, + {"not base64 at all", `{"encoding":"base64","content":"%%%"}`, "with spin-stack/spin grafana", "spin-stack/spin's versions.yaml: illegal base64"}, + {"no versions.yaml", contents("- name: x\n"), "with spin-stack/spin grafana", "spin-stack/spin's versions:"}, + {"no such entry", contents(spinFile), "with spin-stack/spin qemu", "there is no qemu"}, + {"the pin of one that has none", contents(spinFile), "with spin-stack/spin day pin", "grafana is with day's pin, and day has none"}, + } { + t.Run(tc.name, func(t *testing.T) { + files := map[string]string{} + if tc.answer != "" { + files[api] = tc.answer + } + serve(t, files) + v, err := versions.Parse([]byte(strings.Replace(withSpin, "with spin-stack/spin grafana", tc.track, 1))) + require.NoError(t, err) + _, err = newest(t.Context(), v, v.Entries[0]) + assert.ErrorContains(t, err, tc.want) + }) + } +} diff --git a/versions/versions.go b/versions/versions.go index 9b57e64..b48f4e6 100644 --- a/versions/versions.go +++ b/versions/versions.go @@ -229,59 +229,94 @@ func Parse(raw []byte) (*Versions, error) { return v, nil } -// With is the entry e is moved with, and whether e's version is that entry's pin rather than its -// version: track `with `, or `with pin`. ok is false for any other track. -func (e Entry) With() (name string, pin, ok bool) { +// Along is what an entry tracked with another is moved with: the entry Name, in this file or, when +// Repo is set, in the versions.yaml of that GitHub repository (owner/repo); and whether it takes +// that entry's pin rather than its version. +type Along struct { + Repo, Name string + Pin bool +} + +// repository is a GitHub repository as a with track names one: owner/repo. +var repository = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9._-]+$`) + +// With is what e is moved with: track `with [owner/repo] [pin]`. ok is false for any other +// track, and err says a with track that is none of those forms. +func (e Entry) With() (a Along, ok bool, err error) { kind, arg, _ := strings.Cut(e.Track, " ") if kind != "with" { - return "", false, false + return Along{}, false, nil } - name, form, _ := strings.Cut(arg, " ") - return name, form == "pin", true + form := strings.Fields(arg) + if len(form) > 0 && strings.Contains(form[0], "/") { + if !repository.MatchString(form[0]) { + return Along{}, true, fmt.Errorf("versions: %s: %q is not a GitHub repository, owner/repo", e.Name, form[0]) + } + a.Repo, form = form[0], form[1:] + } + if len(form) == 0 || len(form) > 2 || (len(form) == 2 && form[1] != "pin") { + return Along{}, true, fmt.Errorf("versions: %s: the track %q is not with [owner/repo] [pin]", e.Name, e.Track) + } + a.Name, a.Pin = form[0], len(form) == 2 + return a, true, nil } // validateWith is an entry tracked with another whose version the file can say: the other is in // it, is not the entry itself, and is moved by a track of its own, since a chain is one a bump -// would have to walk and a cycle one it never ends. Whether the two agree is not asked here: a -// file in which they do not is one a bump has to be able to read, to move them. +// would have to walk and a cycle one it never ends. One in another repository's file is read only +// by check and bump, which reach it. Whether the two agree is not asked here: a file in which they +// do not is one a bump has to be able to read, to move them. func (v *Versions) validateWith(e Entry) error { - name, pin, ok := e.With() - if !ok { - return nil + a, ok, err := e.With() + if !ok || err != nil || a.Repo != "" { + return err } - _, arg, _ := strings.Cut(e.Track, " ") - if form := strings.Fields(arg); len(form) == 0 || len(form) > 2 || (len(form) == 2 && form[1] != "pin") { - return fmt.Errorf("versions: %s: the track %q is not with or with pin", e.Name, e.Track) - } - if name == e.Name { + if a.Name == e.Name { return fmt.Errorf("versions: %s is with itself", e.Name) } - leader, err := v.Get(name) + leader, err := v.Get(a.Name) if err != nil { - return fmt.Errorf("versions: %s is with %s: %w", e.Name, name, err) + return fmt.Errorf("versions: %s is with %s: %w", e.Name, a.Name, err) } - if _, _, chained := leader.With(); chained { - return fmt.Errorf("versions: %s is with %s, which is with another: name that one", e.Name, name) + if _, chained, _ := leader.With(); chained { + return fmt.Errorf("versions: %s is with %s, which is with another: name that one", e.Name, a.Name) } - if pin && leader.Pin == "" { - return fmt.Errorf("versions: %s is with %s's pin, and %s has none", e.Name, name, name) + if a.Pin && leader.Pin == "" { + return fmt.Errorf("versions: %s is with %s's pin, and %s has none", e.Name, a.Name, a.Name) } return nil } -// Expected is the version an entry tracked with another is at: the other's pin, or its version -// spelled as e spells its own, with a leading v when e's has one. Upstream writes v3.54.0 in a -// tag and 3.54.0 in a file name, and two entries of the same release say it each their own way. +// Expected is the version an entry tracked with another in this file is at: see ExpectedIn. func (v *Versions) Expected(e Entry) (string, error) { - name, pin, ok := e.With() - if !ok { + a, ok, err := e.With() + switch { + case err != nil: + return "", err + case !ok: return "", fmt.Errorf("versions: %s is not tracked with another entry", e.Name) + case a.Repo != "": + return "", fmt.Errorf("versions: %s is with %s's %s, which this file does not have", e.Name, a.Repo, a.Name) } - leader, err := v.Get(name) + return ExpectedIn(e, v) +} + +// ExpectedIn is the version e is at when the file it is with is file: the other's pin, or its +// version spelled as e spells its own, with a leading v when e's has one. Upstream writes v3.54.0 +// in a tag and 3.54.0 in a file name, and two entries of the same release say it each their own way. +func ExpectedIn(e Entry, file *Versions) (string, error) { + a, ok, err := e.With() + if err != nil || !ok { + return "", cmp.Or(err, fmt.Errorf("versions: %s is not tracked with another entry", e.Name)) + } + leader, err := file.Get(a.Name) if err != nil { return "", err } - if pin { + if a.Pin { + if leader.Pin == "" { + return "", fmt.Errorf("versions: %s is with %s's pin, and %s has none", e.Name, a.Name, a.Name) + } return leader.Pin, nil } version := strings.TrimPrefix(leader.Version, "v") @@ -291,11 +326,11 @@ func (v *Versions) Expected(e Entry) (string, error) { return version, nil } -// Followers are the entries tracked with name, in the file's order. +// Followers are the entries tracked with name in this file, in the file's order. func (v *Versions) Followers(name string) []Entry { var out []Entry for _, e := range v.Entries { - if leader, _, ok := e.With(); ok && leader == name { + if a, ok, _ := e.With(); ok && a.Repo == "" && a.Name == name { out = append(out, e) } } diff --git a/versions/versions_test.go b/versions/versions_test.go index 8344b0e..9681d98 100644 --- a/versions/versions_test.go +++ b/versions/versions_test.go @@ -316,7 +316,9 @@ func TestAnEntryWithAnotherNamesOneThatMovesOnItsOwn(t *testing.T) { return "- name: " + name + "\n kind: download\n source: https://y/{version}\n version: '1'\n pin: " + strings.Repeat("b", 64) + "\n track: " + track + "\n" } for _, tc := range []struct{ name, file, want string }{ - {"with no name", lead + follower("f", "with"), `the track "with" is not with or with pin`}, + {"with no name", lead + follower("f", "with"), `the track "with" is not with [owner/repo] [pin]`}, + {"a repository and no name", lead + follower("f", "with o/r"), `the track "with o/r" is not with [owner/repo] [pin]`}, + {"a repository that is not owner/repo", lead + follower("f", "with o/r/x lead"), `"o/r/x" is not a GitHub repository`}, {"a word that is not pin", lead + follower("f", "with lead commit"), `the track "with lead commit" is not`}, {"one word too many", lead + follower("f", "with lead pin x"), `the track "with lead pin x" is not`}, {"itself", lead + follower("f", "with f"), "f is with itself"}, @@ -331,9 +333,18 @@ func TestAnEntryWithAnotherNamesOneThatMovesOnItsOwn(t *testing.T) { } }) } - // Not at the other's version is still a file: a bump has to read it to move them. - if _, err := Parse([]byte(lead + follower("f", "with lead") + follower("g", "with lead pin"))); err != nil { - t.Errorf("entries with another: %v", err) + // Not at the other's version is still a file: a bump has to read it to move them. Another + // repository's entry is not this file's to have. + v, err := Parse([]byte(lead + follower("f", "with lead") + follower("g", "with lead pin") + follower("h", "with spin-stack/spin lead pin"))) + if err != nil { + t.Fatalf("entries with another: %v", err) + } + h, _ := v.Get("h") + if got, err := v.Expected(h); err == nil || !strings.Contains(err.Error(), "h is with spin-stack/spin's lead, which this file does not have") { + t.Errorf("an entry with another repository's, from this file: %q, %v", got, err) + } + if names := v.Followers("lead"); len(names) != 2 { + t.Errorf("followers of lead, another repository's lead included: %v", names) } }