C3: the seat git's tags name each tag's commit, at the seat's form 2

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 <directory>/vMAJOR.MINOR.PATCH, the form the Go toolchain's direct
fallback reads, go/v<version> among them.

Builds: design 47 H2 §796, §780; H-A-350 DMC-3; mesh-delivery D5 d2d3ebbf
This commit is contained in:
2026-11-22 00:42:37 +01:00
parent 5d2d0bade8
commit 4e381c323b
4 changed files with 40 additions and 11 deletions
+8 -2
View File
@@ -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<string[]> {
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<any[]>(`${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). */
+9 -7
View File
@@ -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, <directory>/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<TagsAnswer> => {
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<TreesAnswer> => {
@@ -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<MergePullAnswer> => 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 <directory>/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<TagAnswer> => {
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 <directory>/vMAJOR.MINOR.PATCH`);
const commit = commitOf("commit", args.commit);
const at = await gitea.tagCommit(owner, repo, tag);
if (at === commit) return { tag, performed: true };
+6 -2
View File
@@ -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 <directory>/v<version>.
["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]],
+17
View File
@@ -108,3 +108,20 @@ test("a file over 512 KiB is refused from its directory listing, and its body is
await new Promise<void>((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<void>((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();
}
});