From 4e381c323b7b8a5b337a85e6f09fb12c0e8332a8 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 22 Nov 2026 00:42:37 +0100 Subject: [PATCH] C3: the seat git's tags name each tag's commit, at the seat's form 2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tags answers items {tag, commit} read from the forge's own tag list, a tag the forge names no commit for being an error, never a tag without one; tag writes /vMAJOR.MINOR.PATCH, the form the Go toolchain's direct fallback reads, go/v among them. Builds: design 47 H2 §796, §780; H-A-350 DMC-3; mesh-delivery D5 d2d3ebbf --- modules/gitea/client.ts | 10 ++++++++-- modules/gitea/seat.ts | 16 +++++++++------- modules/gitea/test/guard.test.ts | 8 ++++++-- modules/gitea/test/paging.test.ts | 17 +++++++++++++++++ 4 files changed, 40 insertions(+), 11 deletions(-) diff --git a/modules/gitea/client.ts b/modules/gitea/client.ts index 1b761a8b3..c9cc13f42 100644 --- a/modules/gitea/client.ts +++ b/modules/gitea/client.ts @@ -499,11 +499,17 @@ export class GiteaClient { } /** One page of a repository's tags, newest first, by name: what the seat git's `tags` answers. */ - async tags(owner: string, repo: string, page: number, limit: number): Promise { + async tags(owner: string, repo: string, page: number, limit: number): Promise<{ tag: string; commit: string }[]> { if (!Number.isInteger(page) || page < 1) throw new Error(`${page} is not a page, from 1`); const list = await this.request(`${repoPath(owner, repo)}/tags?page=${page}&limit=${limit}`); if (!Array.isArray(list)) throw new Error(`the forge answered no list of the tags of ${owner}/${repo}`); - return list.map((t) => String(t?.name ?? "")).filter((n) => n !== ""); + // Each tag with the commit it names (design 47 H2 §796): a tag the forge names no commit for is no answer, never a + // tag without its commit. + return list.filter((t) => String(t?.name ?? "") !== "").map((t) => { + const tag = String(t.name), commit = String(t?.commit?.sha ?? ""); + if (!/^[0-9a-f]{40}$/.test(commit)) throw new Error(`the forge named no commit for ${owner}/${repo}'s tag ${tag}`); + return { tag, commit }; + }); } /** The commit a tag names, or null when the repository has no such tag (the forge's 404 only). */ diff --git a/modules/gitea/seat.ts b/modules/gitea/seat.ts index 4af16387d..a9c1804cf 100644 --- a/modules/gitea/seat.ts +++ b/modules/gitea/seat.ts @@ -80,8 +80,10 @@ export function repositoryOf(raw: unknown): { owner: string; repo: string; full: } const SHA = /^[0-9a-f]{40}$/; -/** The git tag of a released Go version (design 51; design 47 §370). */ -const GO_TAG = /^go\/v\d+\.\d+\.\d+$/; +/** The git tag of a released version, /vMAJOR.MINOR.PATCH (design 47 H2 §796; design 47 §370). */ +const VERSION_TAG = /^(?:[A-Za-z0-9_][A-Za-z0-9._-]*\/)+v\d+\.\d+\.\d+$/; +/** The form of the seat git's values and answers this holder answers in (design 47 H2 §780, §796). */ +const GIT_FORM = 2; const STATES = new Set(["pending", "success", "failure", "error", "warning"]); function commitOf(name: string, raw: unknown): string { const sha = String(raw ?? "").trim(); @@ -178,7 +180,7 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[] })); return { pulls }; }), - verb(GIT_VERBS.tags, "The seat git's tags: a repository's tags, a page at a time, newest first; more when another page exists.", + verb(GIT_VERBS.tags, "The seat git's tags: a repository's tags, each with the commit it names, a page at a time, newest first; more when another page exists.", async (args): Promise => { const { owner, repo, full } = repositoryOf(args.repository); const page = args.page === undefined ? 1 : Number(args.page); @@ -186,8 +188,8 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[] // One more than the page is asked, so whether another page exists is the forge's answer, not a guess. const got = await gitea.tags(owner, repo, page, TAGS_PAGE + 1); const more = got.length > TAGS_PAGE; - const tags = got.slice(0, TAGS_PAGE).filter((t) => t.startsWith(prefix)); - return { repository: full, page, bound: TAGS_PAGE, tags, ...(more ? { more } : {}) }; + const tags = got.slice(0, TAGS_PAGE).filter((t) => t.tag.startsWith(prefix)); + return { form: GIT_FORM, repository: full, page, bound: TAGS_PAGE, tags, ...(more ? { more } : {}) }; }), verb(GIT_VERBS.trees, "The seat git's trees: the trees of one commit, with files and paths when asked; a listing the forge cut is refused.", async (args): Promise => { @@ -267,11 +269,11 @@ export function seatTools(gitea: GiteaClient, deps: SeatDeps): ToolDefinition[] }), verb(GIT_VERBS.mergePull, "The seat git's merge-pull: one merge call, a delivery's start and its group: the pull requests named (pulls, each {repository, number, head}) and by (who@node); every member is judged before any is merged (still its head, its base a watched branch, no required step failed at its fingerprint), none merged when one is refused, then each merged in the order named; it answers the call and each member's outcome.", async (args): Promise => mergeCall(gitea, args, deps)), - verb(GIT_VERBS.tag, "The seat git's tag: the git tag go/vMAJOR.MINOR.PATCH of a released version, written at the commit its build was made from; a tag that is at that commit is performed.", + verb(GIT_VERBS.tag, "The seat git's tag: the git tag /vMAJOR.MINOR.PATCH of a released version, written at the commit its build was made from; a tag that is at that commit is performed.", async (args): Promise => { const { owner, repo } = repositoryOf(args.repository); const tag = String(args.tag ?? ""); - if (!GO_TAG.test(tag)) throw new Refused(`${JSON.stringify(tag)} is not go/vMAJOR.MINOR.PATCH`); + if (!VERSION_TAG.test(tag)) throw new Refused(`${JSON.stringify(tag)} is not /vMAJOR.MINOR.PATCH`); const commit = commitOf("commit", args.commit); const at = await gitea.tagCommit(owner, repo, tag); if (at === commit) return { tag, performed: true }; diff --git a/modules/gitea/test/guard.test.ts b/modules/gitea/test/guard.test.ts index ae7348ab7..89215abcb 100644 --- a/modules/gitea/test/guard.test.ts +++ b/modules/gitea/test/guard.test.ts @@ -483,7 +483,7 @@ test("every read and act of the seat git answers its contract, and an error is a appliedProtection: async () => ({ rule_name: "main", enable_status_check: true, status_check_contexts: ["mesh/check"] }), getRepo: async () => ({ writes: true }), openPulls: async () => [{ owner: "novox", repo: "app", number: 9, base: "main", head: "feat/x", head_sha: SHA, required: ["mesh/check"], checks: {} }], - tags: async () => ["go/v0.1.1", "go/v0.1.0", "v1"], + tags: async () => [{ tag: "go/v0.1.1", commit: SHA }, { tag: "go/v0.1.0", commit: OTHER }, { tag: "v1", commit: SHA }], commitTrees: async () => ({ root: SHA, trees: { "": SHA } }), getFile: async (_o: string, _r: string, path: string) => (path === "gone" ? (() => { throw new Error("Gitea API GET /repos/novox/app/contents/gone: 404 Not Found"); })() : path === "down" ? down() : { path, sha: OTHER, size: 3, content: "abc" }), compare: async () => ({ total_commits: 2, commits: [{ sha: OTHER }, { sha: SHA }] }), @@ -509,7 +509,8 @@ test("every read and act of the seat git answers its contract, and an error is a ["branch", "no such branch", { repository: "novox/app", branch: "nope" }, { branchHead: gone }, (a) => [a.head, a["error-kind"]], [undefined, "not-found"]], ["open-pulls", "one", {}, {}, (a) => [a.pulls.length, a.pulls[0].required], [1, ["mesh/check"]]], ["open-pulls", "forge down", {}, { openPulls: down }, (a) => [a.pulls, a["error-kind"]], [undefined, "failed"]], - ["tags", "a page", { repository: "novox/app", prefix: "go/" }, {}, (a) => [a.tags, a.page, a.bound, a.more], [["go/v0.1.1", "go/v0.1.0"], 1, 50, undefined]], + // 47 H2 §796: each tag names its commit, at the seat's form 2. + ["tags", "a page, each tag with its commit", { repository: "novox/app", prefix: "go/" }, {}, (a) => [a.tags, a.page, a.bound, a.more, a.form], [[{ tag: "go/v0.1.1", commit: SHA }, { tag: "go/v0.1.0", commit: OTHER }], 1, 50, undefined, 2]], ["tags", "forge down", { repository: "novox/app" }, { tags: down }, (a) => [a.tags, a["error-kind"]], [undefined, "failed"]], ["trees", "root", { repository: "novox/app", commit: SHA }, {}, (a) => [a.commit, a.root], [SHA, SHA]], ["trees", "forge down", { repository: "novox/app", commit: SHA }, { commitTrees: down }, (a) => [a.root, a["error-kind"]], [undefined, "failed"]], @@ -523,6 +524,9 @@ test("every read and act of the seat git answers its contract, and an error is a ["tag", "written", { repository: "novox/app", tag: "go/v1.2.3", commit: SHA }, { tagCommit: async () => null, createTag: async (_o: string, _r: string, tag: string, c: string) => { tagged.push(`${tag}@${c}`); } }, (a) => [a.performed, tagged.splice(0)], [true, [`go/v1.2.3@${SHA}`]]], ["tag", "already at that commit", { repository: "novox/app", tag: "go/v1.2.3", commit: SHA }, { tagCommit: async () => SHA, createTag: async () => { throw new Error("written again"); } }, (a) => [a.performed, a.error], [true, undefined]], ["tag", "at another commit is never moved", { repository: "novox/app", tag: "go/v1.2.3", commit: SHA }, { tagCommit: async () => OTHER }, (a) => [a.performed, a["error-kind"]], [undefined, "refused"]], + // 47 H2 §796: a Go package's tag is /v. + ["tag", "a package directory's version", { repository: "novox/app", tag: "modules/x/go/v1.2.3", commit: SHA }, { tagCommit: async () => null, createTag: async (_o: string, _r: string, tag: string, c: string) => { tagged.push(`${tag}@${c}`); } }, (a) => [a.performed, tagged.splice(0)], [true, [`modules/x/go/v1.2.3@${SHA}`]]], + ["tag", "no directory", { repository: "novox/app", tag: "v1.2.3", commit: SHA }, {}, (a) => [a.performed, a["error-kind"]], [undefined, "refused"]], ["tag", "no Go version", { repository: "novox/app", tag: "v1", commit: SHA }, {}, (a) => [a.performed, a["error-kind"]], [undefined, "refused"]], ["status", "refused state", { id: "s1", repository: "novox/app", commit: SHA, context: "c", state: "bogus" }, {}, (a) => [a.performed, a["error-kind"]], [undefined, "refused"]], ["comment", "first time", { id: "c1", repository: "novox/app", number: 9, text: "hi" }, {}, (a) => [a.performed, a.held, added], [true, undefined, 1]], diff --git a/modules/gitea/test/paging.test.ts b/modules/gitea/test/paging.test.ts index 8bf0bcca9..c9e7d7845 100644 --- a/modules/gitea/test/paging.test.ts +++ b/modules/gitea/test/paging.test.ts @@ -108,3 +108,20 @@ test("a file over 512 KiB is refused from its directory listing, and its body is await new Promise((r) => server.close(() => r())); } }); + +// 47 H2 §796: a tag names its commit; a tag the forge names no commit for is an error, never a tag without one. +test("the forge's tags are read with the commit each names", async () => { + const { GiteaClient } = await import("../client.ts"); + let body: unknown[] = []; + const server = createServer((_req, res) => res.end(JSON.stringify(body))); + await new Promise((r) => server.listen(0, r)); + try { + const client = new GiteaClient(`http://127.0.0.1:${(server.address() as any).port}`, "t"); + body = [{ name: "go/v0.1.1", commit: { sha: "a".repeat(40) } }, { name: "go/v0.1.0", commit: { sha: "b".repeat(40) } }]; + assert.deepEqual(await client.tags("novox", "hq", 1, 51), [{ tag: "go/v0.1.1", commit: "a".repeat(40) }, { tag: "go/v0.1.0", commit: "b".repeat(40) }]); + body = [{ name: "go/v0.1.2" }]; + await assert.rejects(client.tags("novox", "hq", 1, 51), /named no commit for novox\/hq's tag go\/v0.1.2/); + } finally { + server.close(); + } +});