@niwa-labs/evidence 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +20 -2
- package/package.json +29 -4
- package/src/cockpit/actions.ts +51 -0
- package/src/cockpit/coverage.ts +91 -0
- package/src/cockpit/index.tsx +19 -0
- package/src/cockpit/page.tsx +110 -0
- package/src/index.ts +210 -0
- package/src/records.ts +136 -0
- package/test/cockpit-actions.test.ts +38 -0
- package/test/cockpit-coverage.test.ts +89 -0
- package/test/evidence.test.ts +232 -0
- package/test/queries.test.ts +18 -0
- package/test/run-author.test.ts +51 -0
- package/tsconfig.json +15 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,21 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/evidence
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A plugin that records attestations and what they cover, such as a green
|
|
4
|
+
pipeline for a specific pair of commits.
|
|
5
|
+
|
|
6
|
+
- `evidence.attest { subject, claim }` writes an attestation. Its author is the
|
|
7
|
+
principal of the caller's token, never a field of the payload.
|
|
8
|
+
- `evidence.covers { requirement }` says whether a requirement is covered and,
|
|
9
|
+
when it is not, why: `none`, `target-moved`, `not-merge-result`, `failed` or
|
|
10
|
+
`excluded-author`. A merge result covers only the pair of commits it ran on.
|
|
11
|
+
- `/records`: the record type, the claims, the requirements, the action
|
|
12
|
+
references and the query builder `attested(subject)`, which a script waits for
|
|
13
|
+
or reads with the data typed.
|
|
14
|
+
- `./cockpit`: the cockpit page lists the attestations of each subject, says for each whether it still stands, and
|
|
15
|
+
takes a requirement to ask the host whether it is covered.
|
|
16
|
+
|
|
17
|
+
An attestation counts only if the host's record of who wrote it agrees with its
|
|
18
|
+
author: a client that writes `evidence.attested` straight to the journal cannot
|
|
19
|
+
attest as somebody else. The default author is the principal of the caller's
|
|
20
|
+
token, so a session relaunched under a new token is another author; a composition
|
|
21
|
+
that excludes authors by session or agent passes `bind` to give that address.
|
package/package.json
CHANGED
|
@@ -1,6 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/evidence",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./records": "./src/records.ts",
|
|
9
|
+
"./cockpit": "./src/cockpit/index.tsx"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@niwa-labs/cockpit-sdk": "*",
|
|
13
|
+
"@niwa-labs/core": "*",
|
|
14
|
+
"@niwa-labs/plugin": "*",
|
|
15
|
+
"@niwa-labs/ui-kit": "*",
|
|
16
|
+
"zod": "^4.6.7"
|
|
17
|
+
},
|
|
18
|
+
"devDependencies": {
|
|
19
|
+
"@niwa-labs/testing": "*",
|
|
20
|
+
"@tanstack/react-query": "^5.108.2",
|
|
21
|
+
"@types/react": "^19.3.0",
|
|
22
|
+
"@types/react-dom": "^19.3.0",
|
|
23
|
+
"react": "^19.3.1",
|
|
24
|
+
"react-dom": "^19.3.1"
|
|
25
|
+
},
|
|
26
|
+
"peerDependencies": {
|
|
27
|
+
"@tanstack/react-query": "^5.108.2",
|
|
28
|
+
"react": "^19.3.1",
|
|
29
|
+
"react-dom": "^19.3.1"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The evidence actions as the cockpit calls them: name and the part of each schema the page reads.
|
|
3
|
+
*
|
|
4
|
+
* The module runs in the browser and cannot import the host-side schemas, which reach for Node. A field the host
|
|
5
|
+
* stopped sending fails the page that reads it, which `test/cockpit-actions.test.ts` checks against the real actions.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { z } from "zod";
|
|
9
|
+
|
|
10
|
+
export const Address = z.object({ kind: z.string(), id: z.string().optional(), harness: z.string().optional() }).loose();
|
|
11
|
+
export type Address = z.infer<typeof Address>;
|
|
12
|
+
|
|
13
|
+
const MergeResultClaim = z.object({
|
|
14
|
+
kind: z.literal("ci"),
|
|
15
|
+
at: z.literal("merge-result"),
|
|
16
|
+
sourceSha: z.string(),
|
|
17
|
+
targetSha: z.string(),
|
|
18
|
+
mergeSha: z.string(),
|
|
19
|
+
pipeline: z.number(),
|
|
20
|
+
pipelineKind: z.enum(["merge-result", "train"]),
|
|
21
|
+
});
|
|
22
|
+
const HeadClaim = z.object({ kind: z.literal("ci"), at: z.literal("head"), sha: z.string(), pipeline: z.number() });
|
|
23
|
+
const VerdictClaim = z.object({ kind: z.literal("verdict"), name: z.string(), outcome: z.enum(["pass", "fail"]), sha: z.string() });
|
|
24
|
+
|
|
25
|
+
export const Claim = z.union([MergeResultClaim, HeadClaim, VerdictClaim]);
|
|
26
|
+
export type Claim = z.infer<typeof Claim>;
|
|
27
|
+
|
|
28
|
+
export const Attestation = z.object({ id: z.string(), subject: z.string(), claim: Claim, author: Address, at: z.number() });
|
|
29
|
+
export type Attestation = z.infer<typeof Attestation>;
|
|
30
|
+
|
|
31
|
+
export const listAction = {
|
|
32
|
+
name: "evidence.list",
|
|
33
|
+
input: z.object({ subject: z.string().optional() }),
|
|
34
|
+
output: z.object({ items: z.array(Attestation) }),
|
|
35
|
+
} as const;
|
|
36
|
+
|
|
37
|
+
export const Uncovered = z.enum(["none", "target-moved", "not-merge-result", "failed", "excluded-author"]);
|
|
38
|
+
export type Uncovered = z.infer<typeof Uncovered>;
|
|
39
|
+
|
|
40
|
+
export const Requirement = z.union([
|
|
41
|
+
z.object({ kind: z.literal("ci"), at: z.literal("merge-result"), subject: z.string(), sourceSha: z.string(), targetSha: z.string() }),
|
|
42
|
+
z.object({ kind: z.literal("ci"), at: z.literal("head"), subject: z.string(), sha: z.string() }),
|
|
43
|
+
z.object({ kind: z.literal("verdict"), subject: z.string(), name: z.string(), sha: z.string() }),
|
|
44
|
+
]);
|
|
45
|
+
export type Requirement = z.infer<typeof Requirement>;
|
|
46
|
+
|
|
47
|
+
export const coversAction = {
|
|
48
|
+
name: "evidence.covers",
|
|
49
|
+
input: z.object({ requirement: Requirement }),
|
|
50
|
+
output: z.object({ covered: z.boolean(), by: z.array(z.string()), why: Uncovered.optional() }),
|
|
51
|
+
} as const;
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/** What the evidence page makes of attestations and of the requirement a person asks about. */
|
|
2
|
+
|
|
3
|
+
import type { Address, Attestation, Claim, Requirement, Uncovered } from "./actions.ts";
|
|
4
|
+
|
|
5
|
+
/** A commit id as a person reads it. */
|
|
6
|
+
export function shortSha(sha: string): string {
|
|
7
|
+
return sha.slice(0, 8);
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/** What a claim says, in a sentence. */
|
|
11
|
+
export function claimText(claim: Claim): string {
|
|
12
|
+
if (claim.kind === "verdict") return `${claim.name} · ${claim.outcome === "pass" ? "проверка пройдена" : "проверка не пройдена"} · ${shortSha(claim.sha)}`;
|
|
13
|
+
if (claim.at === "head") return `Пайплайн №${String(claim.pipeline)} успешно проверил коммит ${shortSha(claim.sha)}`;
|
|
14
|
+
const how = claim.pipelineKind === "train" ? "очередь слияния" : "результат слияния";
|
|
15
|
+
return `Пайплайн №${String(claim.pipeline)} прошёл · ${how} ${shortSha(claim.sourceSha)} → ${shortSha(claim.targetSha)}`;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** An address as the page names it. */
|
|
19
|
+
export function who(address: Address): string {
|
|
20
|
+
const kinds: Readonly<Record<string, string>> = { owner: "владелец", client: "клиент", session: "сессия", host: "хост", handler: "обработчик", agent: "агент" };
|
|
21
|
+
const kind = kinds[address.kind] ?? address.kind;
|
|
22
|
+
if (address.harness !== undefined && address.id !== undefined) return `${kind} ${address.harness}/${address.id}`;
|
|
23
|
+
return address.id === undefined ? kind : `${kind} ${address.id}`;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** What it means that a requirement is not covered. */
|
|
27
|
+
export const UNCOVERED_TEXT: Readonly<Record<Uncovered, string>> = {
|
|
28
|
+
none: "Подходящих свидетельств нет.",
|
|
29
|
+
"target-moved": "Свидетельство относится к другому целевому коммиту.",
|
|
30
|
+
"not-merge-result": "Есть проверка исходного коммита. Для требования нужен результат слияния.",
|
|
31
|
+
failed: "Последняя проверка не пройдена.",
|
|
32
|
+
"excluded-author": "Требование исключает авторов всех успешных проверок.",
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
/** The requirement an attestation stands for: what it would cover if nothing else were said about its subject. */
|
|
36
|
+
export function requirementOf(attestation: Pick<Attestation, "subject" | "claim">): Requirement {
|
|
37
|
+
const { subject, claim } = attestation;
|
|
38
|
+
if (claim.kind === "verdict") return { kind: "verdict", subject, name: claim.name, sha: claim.sha };
|
|
39
|
+
if (claim.at === "head") return { kind: "ci", at: "head", subject, sha: claim.sha };
|
|
40
|
+
return { kind: "ci", at: "merge-result", subject, sourceSha: claim.sourceSha, targetSha: claim.targetSha };
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** A requirement as one text, so equal requirements are found equal. */
|
|
44
|
+
export function requirementKey(requirement: Requirement): string {
|
|
45
|
+
return JSON.stringify(Object.entries(requirement).sort(([a], [b]) => a.localeCompare(b)));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The attestations by subject, the subject of the latest attestation first and each subject's latest first. */
|
|
49
|
+
export function bySubject(items: readonly Attestation[]): Array<{ subject: string; attestations: Attestation[] }> {
|
|
50
|
+
const groups = new Map<string, Attestation[]>();
|
|
51
|
+
for (const item of items) {
|
|
52
|
+
const group = groups.get(item.subject);
|
|
53
|
+
if (group === undefined) groups.set(item.subject, [item]);
|
|
54
|
+
else group.push(item);
|
|
55
|
+
}
|
|
56
|
+
const latest = (group: readonly Attestation[]): number => Math.max(...group.map((one) => one.at));
|
|
57
|
+
return [...groups.entries()]
|
|
58
|
+
.map(([subject, attestations]) => ({ subject, attestations: [...attestations].sort((a, b) => b.at - a.at) }))
|
|
59
|
+
.sort((a, b) => latest(b.attestations) - latest(a.attestations));
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** What a person types to ask whether a requirement is covered. */
|
|
63
|
+
export type RequirementForm = {
|
|
64
|
+
kind: "merge-result" | "head" | "verdict";
|
|
65
|
+
subject: string;
|
|
66
|
+
sha: string;
|
|
67
|
+
targetSha: string;
|
|
68
|
+
name: string;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
export const EMPTY_FORM: RequirementForm = { kind: "merge-result", subject: "", sha: "", targetSha: "", name: "" };
|
|
72
|
+
|
|
73
|
+
const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
|
|
74
|
+
|
|
75
|
+
/** The requirement the form describes, or what is wrong with it. */
|
|
76
|
+
export function requirementFromForm(form: RequirementForm): { requirement: Requirement } | { problem: string } {
|
|
77
|
+
const subject = form.subject.trim();
|
|
78
|
+
if (subject === "") return { problem: "Укажите объект, например gitlab.example.com/acme/billing/pr/7." };
|
|
79
|
+
if (subject.length > 512) return { problem: "Длина объекта проверки не должна превышать 512 символов." };
|
|
80
|
+
const sha = form.sha.trim().toLowerCase();
|
|
81
|
+
const sourceName = form.kind === "merge-result" ? "исходного коммита" : "коммита";
|
|
82
|
+
if (!SHA.test(sha)) return { problem: `Укажите полный хеш ${sourceName}.` };
|
|
83
|
+
if (form.kind === "head") return { requirement: { kind: "ci", at: "head", subject, sha } };
|
|
84
|
+
if (form.kind === "verdict") {
|
|
85
|
+
const name = form.name.trim();
|
|
86
|
+
return name === "" ? { problem: "Укажите название проверки, например gates." } : { requirement: { kind: "verdict", subject, name, sha } };
|
|
87
|
+
}
|
|
88
|
+
const targetSha = form.targetSha.trim().toLowerCase();
|
|
89
|
+
if (!SHA.test(targetSha)) return { problem: "Укажите полный хеш целевого коммита." };
|
|
90
|
+
return { requirement: { kind: "ci", at: "merge-result", subject, sourceSha: sha, targetSha } };
|
|
91
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** The cockpit module of the evidence plugin: the attestations of each subject and whether a requirement is covered. */
|
|
2
|
+
|
|
3
|
+
import { definePlugin } from "@niwa-labs/cockpit-sdk";
|
|
4
|
+
|
|
5
|
+
import { EvidencePage } from "./page.tsx";
|
|
6
|
+
|
|
7
|
+
export default definePlugin({
|
|
8
|
+
id: "evidence",
|
|
9
|
+
setup(ctx) {
|
|
10
|
+
ctx.pages.add({
|
|
11
|
+
path: "/evidence",
|
|
12
|
+
title: "Свидетельства",
|
|
13
|
+
commandHeading: true,
|
|
14
|
+
nav: { order: 70 },
|
|
15
|
+
commands: [{ action: "evidence.attest", label: "Добавить свидетельство" }],
|
|
16
|
+
component: EvidencePage,
|
|
17
|
+
});
|
|
18
|
+
},
|
|
19
|
+
});
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/** What was attested about each subject, whether it still stands, and a way to ask whether a requirement is covered. */
|
|
2
|
+
|
|
3
|
+
import { useState } from "react";
|
|
4
|
+
|
|
5
|
+
import { useAction, useCall } from "@niwa-labs/cockpit-sdk";
|
|
6
|
+
import { Button, CopyValue, DataValue, StateRing } from "@niwa-labs/ui-kit";
|
|
7
|
+
|
|
8
|
+
import { coversAction, listAction, type Attestation } from "./actions.ts";
|
|
9
|
+
import { EMPTY_FORM, UNCOVERED_TEXT, bySubject, claimText, requirementFromForm, requirementOf, who, type RequirementForm } from "./coverage.ts";
|
|
10
|
+
|
|
11
|
+
const REFRESH = { refreshOn: { types: ["evidence.attested"] } };
|
|
12
|
+
|
|
13
|
+
/** Whether what an attestation says still stands: the host answers for the requirement it stands for. */
|
|
14
|
+
function Standing({ attestation }: { attestation: Attestation }) {
|
|
15
|
+
const covered = useCall(coversAction, { requirement: requirementOf(attestation) }, REFRESH);
|
|
16
|
+
if (covered.isPending) return <span>Проверяем актуальность…</span>;
|
|
17
|
+
if (covered.isError) return <span>Не удалось проверить актуальность</span>;
|
|
18
|
+
if (!covered.data.covered) return <span>{UNCOVERED_TEXT[covered.data.why ?? "none"]}</span>;
|
|
19
|
+
return <span>{covered.data.by.includes(attestation.id) ? "Подтверждает требование" : "Требование подтверждено другой записью"}</span>;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function AttestationRow({ attestation }: { attestation: Attestation }) {
|
|
23
|
+
const failed = attestation.claim.kind === "verdict" && attestation.claim.outcome === "fail";
|
|
24
|
+
return (
|
|
25
|
+
<li data-slot="attestation-row" data-kind={attestation.claim.kind} className="min-w-0" style={{ display: "grid", gridTemplateColumns: "auto minmax(0, 1fr)", alignItems: "start", columnGap: "0.75rem", paddingBlock: "0.6rem" }}>
|
|
26
|
+
<StateRing state={failed ? "failed" : "done"} label={failed ? "Проверка не пройдена" : "Свидетельство записано"} />
|
|
27
|
+
<div className="flex min-w-0 flex-col gap-1">
|
|
28
|
+
<p className="break-words text-sm font-medium">{claimText(attestation.claim)}</p>
|
|
29
|
+
<p className="desk-tools text-xs text-muted-foreground">
|
|
30
|
+
<span>Автор {who(attestation.author)}</span>
|
|
31
|
+
<time dateTime={new Date(attestation.at).toISOString()}>{new Date(attestation.at).toLocaleString("ru")}</time>
|
|
32
|
+
<CopyValue value={attestation.id} />
|
|
33
|
+
</p>
|
|
34
|
+
<p className="text-xs text-muted-foreground"><Standing attestation={attestation} /></p>
|
|
35
|
+
</div>
|
|
36
|
+
</li>
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function Field({ label, value, onChange }: { label: string; value: string; onChange: (value: string) => void }) {
|
|
41
|
+
return (
|
|
42
|
+
<label className="flex min-w-0 flex-col gap-1 text-xs text-muted-foreground">
|
|
43
|
+
{label}
|
|
44
|
+
<input className="h-8 rounded-md border bg-background px-2 font-mono text-sm text-foreground" value={value} onChange={(event) => onChange(event.target.value)} />
|
|
45
|
+
</label>
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function CoverageCheck() {
|
|
50
|
+
const [form, setForm] = useState<RequirementForm>(EMPTY_FORM);
|
|
51
|
+
const covers = useAction(coversAction);
|
|
52
|
+
const parsed = requirementFromForm(form);
|
|
53
|
+
const set = (change: Partial<RequirementForm>): void => setForm({ ...form, ...change });
|
|
54
|
+
return (
|
|
55
|
+
<section data-slot="coverage-check" className="flex min-w-0 flex-col gap-2 rounded-lg border bg-card p-3 text-card-foreground">
|
|
56
|
+
<h3 className="text-sm font-semibold">Проверить свидетельства для требования</h3>
|
|
57
|
+
<label className="flex flex-col gap-1 text-xs text-muted-foreground">
|
|
58
|
+
Тип требования
|
|
59
|
+
<select className="h-8 rounded-md border bg-background px-2 text-sm text-foreground" value={form.kind} onChange={(event) => set({ kind: event.target.value as RequirementForm["kind"] })}>
|
|
60
|
+
<option value="merge-result">Успешная проверка результата слияния</option>
|
|
61
|
+
<option value="head">Успешный пайплайн коммита</option>
|
|
62
|
+
<option value="verdict">Положительный итог проверки</option>
|
|
63
|
+
</select>
|
|
64
|
+
</label>
|
|
65
|
+
<Field label="Объект проверки" value={form.subject} onChange={(subject) => set({ subject })} />
|
|
66
|
+
<Field label={form.kind === "merge-result" ? "Исходный коммит" : "Коммит"} value={form.sha} onChange={(sha) => set({ sha })} />
|
|
67
|
+
{form.kind === "merge-result" ? <Field label="Целевой коммит" value={form.targetSha} onChange={(targetSha) => set({ targetSha })} /> : null}
|
|
68
|
+
{form.kind === "verdict" ? <Field label="Название проверки" value={form.name} onChange={(name) => set({ name })} /> : null}
|
|
69
|
+
<div className="flex items-center gap-3">
|
|
70
|
+
<Button size="sm" disabled={"problem" in parsed || covers.isPending} onClick={() => "requirement" in parsed && covers.mutate({ requirement: parsed.requirement })}>
|
|
71
|
+
Проверить
|
|
72
|
+
</Button>
|
|
73
|
+
{"problem" in parsed ? <span className="text-xs text-muted-foreground">{parsed.problem}</span> : null}
|
|
74
|
+
</div>
|
|
75
|
+
{covers.isError ? <p role="alert" className="text-xs text-destructive">{covers.error.message}</p> : null}
|
|
76
|
+
{covers.data === undefined ? null : covers.data.covered ? (
|
|
77
|
+
<p role="status" className="flex flex-wrap items-center gap-2 text-sm">Подтверждено записями {covers.data.by.map((id) => <CopyValue key={id} value={id} />)}</p>
|
|
78
|
+
) : (
|
|
79
|
+
<p role="status" className="text-sm text-destructive">Требование пока не подтверждено. {UNCOVERED_TEXT[covers.data.why ?? "none"]}</p>
|
|
80
|
+
)}
|
|
81
|
+
</section>
|
|
82
|
+
);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export function EvidencePage() {
|
|
86
|
+
const attestations = useCall(listAction, {}, REFRESH);
|
|
87
|
+
return (
|
|
88
|
+
<div className="desk-page">
|
|
89
|
+
{attestations.isPending ? (
|
|
90
|
+
<p className="text-sm text-muted-foreground">Загружаем свидетельства…</p>
|
|
91
|
+
) : attestations.isError ? (
|
|
92
|
+
<p role="alert" className="text-sm text-destructive">Не удалось загрузить свидетельства. {attestations.error.message}</p>
|
|
93
|
+
) : attestations.data.items.length === 0 ? (
|
|
94
|
+
<p className="text-sm text-muted-foreground">Свидетельств пока нет. Здесь появятся подтверждения проверок и результаты сборок.</p>
|
|
95
|
+
) : (
|
|
96
|
+
bySubject(attestations.data.items).map((group) => (
|
|
97
|
+
<section key={group.subject} data-slot="subject" className="flex min-w-0 flex-col gap-1">
|
|
98
|
+
<h3 className="text-sm font-semibold"><DataValue value={group.subject} /></h3>
|
|
99
|
+
<ul className="divide-y rounded-lg border bg-card px-3 text-card-foreground">
|
|
100
|
+
{group.attestations.map((attestation) => (
|
|
101
|
+
<AttestationRow key={attestation.id} attestation={attestation} />
|
|
102
|
+
))}
|
|
103
|
+
</ul>
|
|
104
|
+
</section>
|
|
105
|
+
))
|
|
106
|
+
)}
|
|
107
|
+
<CoverageCheck />
|
|
108
|
+
</div>
|
|
109
|
+
);
|
|
110
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The evidence module: attestations and what they cover.
|
|
3
|
+
*
|
|
4
|
+
* `evidence.attest` writes one attestation, with the caller as its author: the transport binds who
|
|
5
|
+
* called (`bind`, by default a client speaks as itself and the owner as the owner), and a caller that
|
|
6
|
+
* stands for nobody (the host, a handler with no address) cannot attest. `evidence.covers` answers
|
|
7
|
+
* whether a requirement is covered, from the attestations alone, and why not when it is not.
|
|
8
|
+
*
|
|
9
|
+
* Coverage is exact: a merge result covers the pair of commits it ran on and no other, so a target
|
|
10
|
+
* branch that moved makes it stale; an ordinary pipeline of the head is not a merge result; a verdict
|
|
11
|
+
* covers the commit it was given on, and not when every passing one is by an author the requirement
|
|
12
|
+
* excludes (the author of the patch, for one) or a later one failed.
|
|
13
|
+
*
|
|
14
|
+
* An attestation counts only when the caller the host recorded for it is the author it names, so a
|
|
15
|
+
* principal allowed to write the record type cannot put another's name on it. Reads take the journal by
|
|
16
|
+
* subject, and a list is paged.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
import { fileURLToPath } from "node:url";
|
|
20
|
+
|
|
21
|
+
import { CatchableError, action, seq, stableJson } from "@niwa-labs/core";
|
|
22
|
+
import type { Address, Caller, JournalReader, StoredRecord } from "@niwa-labs/core";
|
|
23
|
+
import { COCKPIT_MODULE, bindingOf, plugin } from "@niwa-labs/plugin";
|
|
24
|
+
import type { CallerBinding, Plugin } from "@niwa-labs/plugin";
|
|
25
|
+
|
|
26
|
+
import { Attested, EVIDENCE_TYPES, evidenceAttest, evidenceCovers, evidenceList } from "./records.ts";
|
|
27
|
+
import type { Attestation, Requirement, Uncovered } from "./records.ts";
|
|
28
|
+
|
|
29
|
+
export * from "./records.ts";
|
|
30
|
+
|
|
31
|
+
/** Why an attestation was not written, or a read was not answered. */
|
|
32
|
+
export type EvidenceRefusalCode = "no-author" | "journal-unavailable";
|
|
33
|
+
|
|
34
|
+
/** A refusal of the evidence module: the caller's to catch. */
|
|
35
|
+
export class EvidenceRefusal extends CatchableError {
|
|
36
|
+
override name = "EvidenceRefusal";
|
|
37
|
+
override readonly code: EvidenceRefusalCode;
|
|
38
|
+
|
|
39
|
+
constructor(code: EvidenceRefusalCode, message: string) {
|
|
40
|
+
super(message);
|
|
41
|
+
this.code = code;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** What the evidence module is given. */
|
|
46
|
+
export interface EvidenceOptions {
|
|
47
|
+
/**
|
|
48
|
+
* The address a caller attests as. Default: `principalBinding`.
|
|
49
|
+
*
|
|
50
|
+
* It must be a function of the caller alone: coverage binds the recorded caller of every attestation
|
|
51
|
+
* again when it reads it, and an attestation whose author the binding no longer gives is not counted.
|
|
52
|
+
* A composition that excludes an author by session or agent (`notBy`) supplies a binding that gives
|
|
53
|
+
* that address, so the exclusion holds when the session is relaunched under a new token.
|
|
54
|
+
*/
|
|
55
|
+
readonly bind?: CallerBinding;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The default binding of an author: the principal of the connection's token, which stays the same
|
|
60
|
+
* across the connections of that token but not across a new one (a session relaunched under a new
|
|
61
|
+
* token is another client here). The owner attests as the owner; another principal as the client
|
|
62
|
+
* `<kind>:<id>` (`session:reviewer`, `run:r-12`); a connection with no principal as itself. The host
|
|
63
|
+
* and a handler stand for nobody.
|
|
64
|
+
*/
|
|
65
|
+
export const principalBinding: CallerBinding = (caller) => {
|
|
66
|
+
if (caller.kind !== "client") return undefined;
|
|
67
|
+
if (caller.principal === undefined) return bindingOf()(caller);
|
|
68
|
+
if (caller.principal.kind === "owner") return { kind: "owner" };
|
|
69
|
+
return { kind: "client", id: `${caller.principal.kind}:${caller.principal.id}` };
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
/** How many attestations a read of the journal takes at a time. */
|
|
73
|
+
const BATCH = 500;
|
|
74
|
+
|
|
75
|
+
/** The default size of a page of `evidence.list`. */
|
|
76
|
+
const PAGE = 100;
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Whether the host-recorded writer of a record stands behind the author in its payload. A client wrote
|
|
80
|
+
* as the address the binding gives it, so a payload that names another author is not its own. The host
|
|
81
|
+
* and a handler (a workflow run attesting through its call) have no principal in the record to check.
|
|
82
|
+
*/
|
|
83
|
+
function writtenBy(actor: Caller, author: Address, bind: CallerBinding): boolean {
|
|
84
|
+
if (actor.kind !== "client") return true;
|
|
85
|
+
const bound = bind(actor);
|
|
86
|
+
return bound !== undefined && stableJson(bound) === stableJson(author);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function attestationOf(stored: StoredRecord, bind: CallerBinding): Attestation | undefined {
|
|
90
|
+
const parsed = Attested.schema.safeParse(stored.data);
|
|
91
|
+
if (!parsed.success || !writtenBy(stored.actor, parsed.data.author, bind)) return undefined;
|
|
92
|
+
return { id: stored.id, seq: stored.seq, at: stored.at, ...parsed.data };
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** What a read of the attestations asks for. */
|
|
96
|
+
export interface AttestationQuery {
|
|
97
|
+
/** Only this subject's. */
|
|
98
|
+
readonly subject?: string;
|
|
99
|
+
/** Only those written after this position. */
|
|
100
|
+
readonly after?: number;
|
|
101
|
+
/** At most this many. */
|
|
102
|
+
readonly limit?: number;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The attestations of the journal in the order they were written, the ones a caller really wrote. A
|
|
107
|
+
* subject is read by its key, so the history of other subjects is neither loaded nor parsed. With a
|
|
108
|
+
* `limit`, `next` is the position to go on after when the page is full. A journal that is not there
|
|
109
|
+
* is an error: an empty history is an answer only of a journal that was read.
|
|
110
|
+
*/
|
|
111
|
+
export function readAttestations(
|
|
112
|
+
journal: JournalReader | undefined,
|
|
113
|
+
bind: CallerBinding,
|
|
114
|
+
query: AttestationQuery,
|
|
115
|
+
): { items: Attestation[]; next?: number } {
|
|
116
|
+
if (journal === undefined) throw new EvidenceRefusal("journal-unavailable", "the journal cannot be read now, so nothing can be said about what was attested");
|
|
117
|
+
const items: Attestation[] = [];
|
|
118
|
+
let cursor = query.after ?? 0;
|
|
119
|
+
for (;;) {
|
|
120
|
+
const rows =
|
|
121
|
+
query.subject === undefined
|
|
122
|
+
? journal.since(seq(cursor), [Attested.name], BATCH)
|
|
123
|
+
: journal.find({ type: Attested.name, field: "subject", equals: query.subject, after: seq(cursor) });
|
|
124
|
+
for (const row of rows) {
|
|
125
|
+
cursor = row.seq;
|
|
126
|
+
const one = attestationOf(row, bind);
|
|
127
|
+
if (one === undefined) continue;
|
|
128
|
+
items.push(one);
|
|
129
|
+
if (query.limit !== undefined && items.length === query.limit) return { items, next: row.seq };
|
|
130
|
+
}
|
|
131
|
+
if (query.subject !== undefined || rows.length < BATCH) return { items };
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** Whether the requirement is covered by these attestations of its subject, and by which. */
|
|
136
|
+
export function coverage(all: readonly Attestation[], requirement: Requirement): { covered: boolean; by: string[]; why?: Uncovered } {
|
|
137
|
+
const selected = (pipeline: number) => requirement.kind !== "ci" || requirement.at !== "merge-result" || requirement.pipeline === undefined || requirement.pipeline === pipeline;
|
|
138
|
+
const mine = all.filter((one) => one.subject === requirement.subject);
|
|
139
|
+
const no = (why: Uncovered) => ({ covered: false, by: [], why });
|
|
140
|
+
if (requirement.kind === "ci" && requirement.at === "merge-result") {
|
|
141
|
+
const results = mine.flatMap((one) => (one.claim.kind === "ci" && one.claim.at === "merge-result" && one.claim.sourceSha === requirement.sourceSha && selected(one.claim.pipeline) ? [{ one, claim: one.claim }] : []));
|
|
142
|
+
const exact = results.filter(({ claim }) => claim.targetSha === requirement.targetSha);
|
|
143
|
+
if (exact.length > 0) return { covered: true, by: exact.map(({ one }) => one.id) };
|
|
144
|
+
if (results.length > 0) return no("target-moved");
|
|
145
|
+
const head = mine.some((one) => one.claim.kind === "ci" && one.claim.at === "head" && one.claim.sha === requirement.sourceSha && selected(one.claim.pipeline));
|
|
146
|
+
return no(head ? "not-merge-result" : "none");
|
|
147
|
+
}
|
|
148
|
+
if (requirement.kind === "ci") {
|
|
149
|
+
const heads = mine.filter((one) => one.claim.kind === "ci" && one.claim.at === "head" && one.claim.sha === requirement.sha);
|
|
150
|
+
return heads.length > 0 ? { covered: true, by: heads.map((one) => one.id) } : no("none");
|
|
151
|
+
}
|
|
152
|
+
const verdicts = mine.flatMap((one) => (one.claim.kind === "verdict" && one.claim.name === requirement.name && one.claim.sha === requirement.sha ? [{ one, claim: one.claim }] : []));
|
|
153
|
+
if (verdicts.length === 0) return no("none");
|
|
154
|
+
const excluded = new Set((requirement.notBy ?? []).map((address) => stableJson(address)));
|
|
155
|
+
const allowed = verdicts.filter(({ one }) => !excluded.has(stableJson(one.author)));
|
|
156
|
+
if (allowed.length === 0) return no("excluded-author");
|
|
157
|
+
const last = allowed.at(-1);
|
|
158
|
+
if (last === undefined || last.claim.outcome === "fail") return no("failed");
|
|
159
|
+
return { covered: true, by: [last.one.id] };
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** The evidence module. */
|
|
163
|
+
export function evidence(options: EvidenceOptions = {}): Plugin {
|
|
164
|
+
const bind = options.bind ?? principalBinding;
|
|
165
|
+
|
|
166
|
+
return plugin("evidence", (api) => {
|
|
167
|
+
api.declare(...EVIDENCE_TYPES);
|
|
168
|
+
// The page of this plugin in the cockpit: a client module, offered by the path of its source.
|
|
169
|
+
api.offer(COCKPIT_MODULE, { id: "evidence", entry: fileURLToPath(new URL("./cockpit/index.tsx", import.meta.url)) });
|
|
170
|
+
const journal = (): JournalReader | undefined => api.journal?.();
|
|
171
|
+
|
|
172
|
+
api.action(
|
|
173
|
+
action(evidenceAttest, {
|
|
174
|
+
// The record follows the operation, so a repeat answers the attestation it wrote.
|
|
175
|
+
recovery: "repeat",
|
|
176
|
+
effect: "record",
|
|
177
|
+
world: "niwa",
|
|
178
|
+
async run(input, ctx) {
|
|
179
|
+
const author = bind(ctx.caller);
|
|
180
|
+
if (author === undefined) throw new EvidenceRefusal("no-author", "an attestation needs an author, and this caller speaks for nobody");
|
|
181
|
+
const stored = await ctx.emit(Attested, { subject: input.subject, claim: input.claim, author });
|
|
182
|
+
return { id: stored.id, author };
|
|
183
|
+
},
|
|
184
|
+
}),
|
|
185
|
+
);
|
|
186
|
+
|
|
187
|
+
api.action(
|
|
188
|
+
action(evidenceCovers, {
|
|
189
|
+
recovery: "repeat",
|
|
190
|
+
effect: "read",
|
|
191
|
+
world: "niwa",
|
|
192
|
+
run: (input) => coverage(readAttestations(journal(), bind, { subject: input.requirement.subject }).items, input.requirement),
|
|
193
|
+
}),
|
|
194
|
+
);
|
|
195
|
+
|
|
196
|
+
api.action(
|
|
197
|
+
action(evidenceList, {
|
|
198
|
+
recovery: "repeat",
|
|
199
|
+
effect: "read",
|
|
200
|
+
world: "niwa",
|
|
201
|
+
run: (input) =>
|
|
202
|
+
readAttestations(journal(), bind, {
|
|
203
|
+
...(input.subject === undefined ? {} : { subject: input.subject }),
|
|
204
|
+
...(input.after === undefined ? {} : { after: input.after }),
|
|
205
|
+
limit: input.limit ?? PAGE,
|
|
206
|
+
}),
|
|
207
|
+
}),
|
|
208
|
+
);
|
|
209
|
+
});
|
|
210
|
+
}
|
package/src/records.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The records entry of the evidence module: an attestation, what it may claim, the requirements it
|
|
3
|
+
* may cover, and the typed references to the actions.
|
|
4
|
+
*
|
|
5
|
+
* An attestation says that something was shown about a subject (a pull request, a plan node) at a
|
|
6
|
+
* precise state of the code. Its author is whoever the transport says called, never a field of the
|
|
7
|
+
* payload. A requirement is covered only by an attestation of the same state: a green merge result
|
|
8
|
+
* covers a merge only for the pair of commits it ran on, so a target branch that moved since, or an
|
|
9
|
+
* ordinary pipeline of the head in place of a merge result, covers nothing.
|
|
10
|
+
*
|
|
11
|
+
* The names of the commits follow those of the forge module's pipelines (`sourceSha`, `targetSha`,
|
|
12
|
+
* `mergeSha`, `pipeline`), so a pipeline record can be attested as it is.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import { Address, actionRef, queryOf, record } from "@niwa-labs/core";
|
|
16
|
+
import type { TypeQuery } from "@niwa-labs/core";
|
|
17
|
+
import { z } from "zod";
|
|
18
|
+
|
|
19
|
+
/** A full commit id: a SHA-1 (40 hex characters) or a SHA-256 (64) object id. */
|
|
20
|
+
export const Sha = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/, "a full commit id");
|
|
21
|
+
|
|
22
|
+
/** The name of a check (`gates`, `live`), the same for a verdict and for a requirement of one. */
|
|
23
|
+
export const VerdictName = z.string().min(1).max(100);
|
|
24
|
+
|
|
25
|
+
/** What an attestation is about: `gitlab.example.com/acme/billing/pr/7`, `plan/rev-3/node-2`. */
|
|
26
|
+
export const Subject = z.string().min(1).max(512);
|
|
27
|
+
|
|
28
|
+
/** A green pipeline of a merge result or a merge train: the merge of `sourceSha` into `targetSha`. */
|
|
29
|
+
export const MergeResultClaim = z.strictObject({
|
|
30
|
+
kind: z.literal("ci"),
|
|
31
|
+
at: z.literal("merge-result"),
|
|
32
|
+
sourceSha: Sha,
|
|
33
|
+
targetSha: Sha,
|
|
34
|
+
mergeSha: Sha,
|
|
35
|
+
pipeline: z.number().int().positive(),
|
|
36
|
+
pipelineKind: z.enum(["merge-result", "train"]),
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
/** A green pipeline of a head, alone. */
|
|
40
|
+
export const HeadClaim = z.strictObject({
|
|
41
|
+
kind: z.literal("ci"),
|
|
42
|
+
at: z.literal("head"),
|
|
43
|
+
sha: Sha,
|
|
44
|
+
pipeline: z.number().int().positive(),
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
/** A verdict of a named check (`gates`, `live`) on a commit. */
|
|
48
|
+
export const VerdictClaim = z.strictObject({
|
|
49
|
+
kind: z.literal("verdict"),
|
|
50
|
+
name: VerdictName,
|
|
51
|
+
outcome: z.enum(["pass", "fail"]),
|
|
52
|
+
sha: Sha,
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
/** What an attestation claims. */
|
|
56
|
+
export const Claim = z.union([MergeResultClaim, HeadClaim, VerdictClaim]);
|
|
57
|
+
export type Claim = z.infer<typeof Claim>;
|
|
58
|
+
|
|
59
|
+
/** Something was attested. The author is the caller's address, as the transport bound it. */
|
|
60
|
+
export const Attested = record(
|
|
61
|
+
"evidence.attested",
|
|
62
|
+
z.strictObject({ subject: Subject, claim: Claim, author: Address }),
|
|
63
|
+
);
|
|
64
|
+
export type AttestedData = z.infer<typeof Attested.schema>;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The attestations about one subject, as a script waits for or reads them with their data typed:
|
|
68
|
+
* `await wait(attested(subject), { timeout: "1h" })`.
|
|
69
|
+
*/
|
|
70
|
+
export function attested(subject: string): TypeQuery<AttestedData> {
|
|
71
|
+
return queryOf(Attested, { subject: Subject.parse(subject) });
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** A requirement an attestation may cover. */
|
|
75
|
+
export const Requirement = z.union([
|
|
76
|
+
/**
|
|
77
|
+
* A green merge result of exactly this pair of commits. `pipeline` is the pipeline the forge selected
|
|
78
|
+
* for the merge request now: when it is given, only an attestation of that pipeline counts, so an
|
|
79
|
+
* earlier merge result does not cover a merge request whose selected pipeline is an ordinary one.
|
|
80
|
+
*/
|
|
81
|
+
z.strictObject({
|
|
82
|
+
kind: z.literal("ci"),
|
|
83
|
+
at: z.literal("merge-result"),
|
|
84
|
+
subject: Subject,
|
|
85
|
+
sourceSha: Sha,
|
|
86
|
+
targetSha: Sha,
|
|
87
|
+
pipeline: z.number().int().positive().optional(),
|
|
88
|
+
}),
|
|
89
|
+
/** A green pipeline of this head. */
|
|
90
|
+
z.strictObject({ kind: z.literal("ci"), at: z.literal("head"), subject: Subject, sha: Sha }),
|
|
91
|
+
/** A passing verdict of this name on this commit, from none of `notBy`. */
|
|
92
|
+
z.strictObject({ kind: z.literal("verdict"), subject: Subject, name: VerdictName, sha: Sha, notBy: z.array(Address).optional() }),
|
|
93
|
+
]);
|
|
94
|
+
export type Requirement = z.infer<typeof Requirement>;
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Why a requirement is not covered: nothing was attested; the merge result ran on another target
|
|
98
|
+
* commit (the target branch moved); only an ordinary pipeline of the head ran; the verdict failed;
|
|
99
|
+
* every passing verdict is by an author the requirement excludes.
|
|
100
|
+
*/
|
|
101
|
+
export const Uncovered = z.enum(["none", "target-moved", "not-merge-result", "failed", "excluded-author"]);
|
|
102
|
+
export type Uncovered = z.infer<typeof Uncovered>;
|
|
103
|
+
|
|
104
|
+
/** One attestation, as the module lists it. */
|
|
105
|
+
export const Attestation = z.strictObject({ id: z.string(), seq: z.number().int().nonnegative(), subject: Subject, claim: Claim, author: Address, at: z.number() });
|
|
106
|
+
export type Attestation = z.infer<typeof Attestation>;
|
|
107
|
+
|
|
108
|
+
export const evidenceAttest = actionRef("evidence.attest", {
|
|
109
|
+
description:
|
|
110
|
+
"Attest something about a subject at a precise state of the code: a green merge result of a pair of commits, a green " +
|
|
111
|
+
"pipeline of a head, a verdict of a named check on a commit. The author is the caller, as the connection says; it is not " +
|
|
112
|
+
"given. Answers the attestation's id.",
|
|
113
|
+
input: z.strictObject({ subject: Subject, claim: Claim }),
|
|
114
|
+
output: z.strictObject({ id: z.string(), author: Address }),
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
export const evidenceCovers = actionRef("evidence.covers", {
|
|
118
|
+
description:
|
|
119
|
+
"Whether a requirement is covered by an attestation of the same state, and by which. A merge result covers only the pair " +
|
|
120
|
+
"of commits it ran on: when the target branch moved, or GitLab ran an ordinary pipeline of the head instead of a merge " +
|
|
121
|
+
"result, it is not covered and `why` says so. Give the `pipeline` the forge selected for the merge request to hold the " +
|
|
122
|
+
"requirement to that pipeline alone. A read that cannot reach the journal is refused, not answered as `none`.",
|
|
123
|
+
input: z.strictObject({ requirement: Requirement }),
|
|
124
|
+
output: z.strictObject({ covered: z.boolean(), by: z.array(z.string()), why: Uncovered.optional() }),
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
export const evidenceList = actionRef("evidence.list", {
|
|
128
|
+
description:
|
|
129
|
+
"The attestations of a subject, or every attestation, in the order they were written, a page at a time: `limit` of them " +
|
|
130
|
+
"(default 100) after the position `after`. `next` is the `after` of the following page, and is absent on the last one.",
|
|
131
|
+
input: z.strictObject({ subject: Subject.optional(), after: z.number().int().nonnegative().optional(), limit: z.number().int().min(1).max(500).optional() }),
|
|
132
|
+
output: z.strictObject({ items: z.array(Attestation), next: z.number().int().nonnegative().optional() }),
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
/** Every record type of the evidence module. */
|
|
136
|
+
export const EVIDENCE_TYPES = [Attested] as const;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// The copy of the evidence actions the cockpit module keeps reads what the host answers, and the host lists the module.
|
|
2
|
+
|
|
3
|
+
import { expect, test } from "bun:test";
|
|
4
|
+
import { actionName } from "@niwa-labs/core";
|
|
5
|
+
import { createNiwa, tempHome, unreadable, unsendable } from "@niwa-labs/testing";
|
|
6
|
+
|
|
7
|
+
import { evidence } from "../src/index.ts";
|
|
8
|
+
import { Attestation, Claim, evidenceCovers, evidenceList } from "../src/records.ts";
|
|
9
|
+
import { Attestation as AttestationCopy, Claim as ClaimCopy, coversAction, listAction } from "../src/cockpit/actions.ts";
|
|
10
|
+
|
|
11
|
+
test.each([
|
|
12
|
+
["evidence.list", listAction, evidenceList],
|
|
13
|
+
["evidence.covers", coversAction, evidenceCovers],
|
|
14
|
+
] as const)("%s is sent as the host takes it and its answer is read", (name, copy, real) => {
|
|
15
|
+
expect(String(copy.name)).toBe(name);
|
|
16
|
+
expect(String(real.name)).toBe(name);
|
|
17
|
+
expect(unsendable(copy.input, real.input)).toEqual([]);
|
|
18
|
+
expect(unreadable(copy.output, real.output)).toEqual([]);
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
test("a claim and an attestation of the host are read whole", () => {
|
|
22
|
+
expect(unreadable(ClaimCopy, Claim)).toEqual([]);
|
|
23
|
+
expect(unreadable(AttestationCopy, Attestation)).toEqual([]);
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
test("the plugin offers its page to the cockpit", async () => {
|
|
27
|
+
const home = await tempHome();
|
|
28
|
+
const niwa = createNiwa({ home: home.path });
|
|
29
|
+
try {
|
|
30
|
+
niwa.use(evidence());
|
|
31
|
+
await niwa.serve();
|
|
32
|
+
const catalog = (await niwa.call(actionName("niwa.cockpit.catalog"), {})) as { modules: Array<{ id: string; plugin: string }> };
|
|
33
|
+
expect(catalog.modules).toContainEqual(expect.objectContaining({ id: "evidence", plugin: "evidence" }));
|
|
34
|
+
} finally {
|
|
35
|
+
await niwa.close();
|
|
36
|
+
await home.cleanup();
|
|
37
|
+
}
|
|
38
|
+
});
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
// The evidence page: what an attestation says, the requirement it stands for, and the form that asks about one.
|
|
2
|
+
|
|
3
|
+
import { expect, test } from "bun:test";
|
|
4
|
+
|
|
5
|
+
import { evidenceCovers } from "../src/records.ts";
|
|
6
|
+
import type { Attestation } from "../src/cockpit/actions.ts";
|
|
7
|
+
import { EMPTY_FORM, bySubject, claimText, requirementFromForm, requirementKey, requirementOf, shortSha, who } from "../src/cockpit/coverage.ts";
|
|
8
|
+
|
|
9
|
+
const A = "a".repeat(40);
|
|
10
|
+
const B = "b".repeat(40);
|
|
11
|
+
const C = "c".repeat(40);
|
|
12
|
+
const OWNER = { kind: "owner" };
|
|
13
|
+
|
|
14
|
+
const merge = (subject: string, at: number): Attestation => ({
|
|
15
|
+
id: `e-${String(at)}`,
|
|
16
|
+
subject,
|
|
17
|
+
at,
|
|
18
|
+
author: OWNER,
|
|
19
|
+
claim: { kind: "ci", at: "merge-result", sourceSha: A, targetSha: B, mergeSha: C, pipeline: 12, pipelineKind: "merge-result" },
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
test("a claim reads as a sentence with short commit ids", () => {
|
|
23
|
+
expect(shortSha(A)).toBe("aaaaaaaa");
|
|
24
|
+
expect(claimText(merge("pr", 1).claim)).toBe("Пайплайн №12 прошёл · результат слияния aaaaaaaa → bbbbbbbb");
|
|
25
|
+
expect(claimText({ kind: "ci", at: "head", sha: A, pipeline: 3 })).toBe("Пайплайн №3 успешно проверил коммит aaaaaaaa");
|
|
26
|
+
expect(claimText({ kind: "verdict", name: "gates", outcome: "fail", sha: A })).toBe("gates · проверка не пройдена · aaaaaaaa");
|
|
27
|
+
expect(claimText({ kind: "ci", at: "merge-result", sourceSha: A, targetSha: B, mergeSha: C, pipeline: 4, pipelineKind: "train" })).toContain("очередь слияния");
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
test("an author is named by its kind and what it names", () => {
|
|
31
|
+
expect(who(OWNER)).toBe("владелец");
|
|
32
|
+
expect(who({ kind: "client", id: "session:reviewer" })).toBe("клиент session:reviewer");
|
|
33
|
+
expect(who({ kind: "session", harness: "claude", id: "abc" })).toBe("сессия claude/abc");
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
test("subjects are listed by their latest attestation, and each subject's latest first", () => {
|
|
37
|
+
const groups = bySubject([merge("old", 1), merge("new", 5), merge("old", 3), merge("mid", 4)]);
|
|
38
|
+
expect(groups.map((group) => group.subject)).toEqual(["new", "mid", "old"]);
|
|
39
|
+
expect(groups[2]?.attestations.map((one) => one.at)).toEqual([3, 1]);
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
test("an attestation stands for the requirement it would cover, and equal ones share a key", () => {
|
|
43
|
+
expect(requirementOf(merge("pr", 1))).toEqual({ kind: "ci", at: "merge-result", subject: "pr", sourceSha: A, targetSha: B });
|
|
44
|
+
expect(requirementOf({ subject: "pr", claim: { kind: "ci", at: "head", sha: A, pipeline: 1 } })).toEqual({ kind: "ci", at: "head", subject: "pr", sha: A });
|
|
45
|
+
expect(requirementOf({ subject: "pr", claim: { kind: "verdict", name: "gates", outcome: "pass", sha: A } })).toEqual({ kind: "verdict", subject: "pr", name: "gates", sha: A });
|
|
46
|
+
expect(requirementKey(requirementOf(merge("pr", 1)))).toBe(requirementKey(requirementOf(merge("pr", 9))));
|
|
47
|
+
expect(requirementKey(requirementOf(merge("pr", 1)))).not.toBe(requirementKey(requirementOf(merge("other", 1))));
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
test("every requirement the page builds is one the host takes", () => {
|
|
51
|
+
const requirements = [
|
|
52
|
+
requirementOf(merge("pr", 1)),
|
|
53
|
+
requirementOf({ subject: "pr", claim: { kind: "ci", at: "head", sha: A, pipeline: 1 } }),
|
|
54
|
+
requirementOf({ subject: "pr", claim: { kind: "verdict", name: "gates", outcome: "pass", sha: A } }),
|
|
55
|
+
];
|
|
56
|
+
const fromForms = [
|
|
57
|
+
requirementFromForm({ kind: "merge-result", subject: "pr", sha: A, targetSha: B, name: "" }),
|
|
58
|
+
requirementFromForm({ kind: "head", subject: "pr", sha: A, targetSha: "", name: "" }),
|
|
59
|
+
requirementFromForm({ kind: "verdict", subject: "pr", sha: A, targetSha: "", name: "gates" }),
|
|
60
|
+
].map((one) => ("requirement" in one ? one.requirement : undefined));
|
|
61
|
+
for (const requirement of [...requirements, ...fromForms]) {
|
|
62
|
+
expect(requirement).toBeDefined();
|
|
63
|
+
expect(evidenceCovers.input.safeParse({ requirement }).success).toBe(true);
|
|
64
|
+
}
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
test("the form refuses what the host would refuse, and says what is wrong", () => {
|
|
68
|
+
expect(requirementFromForm(EMPTY_FORM)).toEqual({ problem: "Укажите объект, например gitlab.example.com/acme/billing/pr/7." });
|
|
69
|
+
expect(requirementFromForm({ ...EMPTY_FORM, subject: "pr", sha: "abc123" })).toEqual({ problem: "Укажите полный хеш исходного коммита." });
|
|
70
|
+
expect(requirementFromForm({ ...EMPTY_FORM, kind: "head", subject: "pr", sha: "abc123" })).toEqual({ problem: "Укажите полный хеш коммита." });
|
|
71
|
+
expect(requirementFromForm({ ...EMPTY_FORM, subject: "pr", sha: A, targetSha: "nope" })).toEqual({ problem: "Укажите полный хеш целевого коммита." });
|
|
72
|
+
expect(requirementFromForm({ ...EMPTY_FORM, kind: "verdict", subject: "pr", sha: A })).toEqual({ problem: "Укажите название проверки, например gates." });
|
|
73
|
+
expect(requirementFromForm({ ...EMPTY_FORM, subject: "x".repeat(513), sha: A, targetSha: B })).toEqual({ problem: "Длина объекта проверки не должна превышать 512 символов." });
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
test("the form trims what is typed and reads commit ids in lower case", () => {
|
|
77
|
+
expect(requirementFromForm({ kind: "head", subject: " pr ", sha: ` ${A.toUpperCase()} `, targetSha: "", name: "" })).toEqual({
|
|
78
|
+
requirement: { kind: "ci", at: "head", subject: "pr", sha: A },
|
|
79
|
+
});
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
test("the form takes the commit ids the host takes and no others", () => {
|
|
83
|
+
for (const length of [39, 40, 41, 63, 64, 65]) {
|
|
84
|
+
const id = "d".repeat(length);
|
|
85
|
+
const built = requirementFromForm({ kind: "merge-result", subject: "pr", sha: id, targetSha: id, name: "" });
|
|
86
|
+
const taken = "requirement" in built && evidenceCovers.input.safeParse({ requirement: built.requirement }).success;
|
|
87
|
+
expect([length, "requirement" in built]).toEqual([length, taken]);
|
|
88
|
+
}
|
|
89
|
+
});
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
// Attestations: the author the transport binds, and coverage of a merge result bound to the pair of
|
|
2
|
+
// commits it ran on.
|
|
3
|
+
|
|
4
|
+
import { afterEach, expect, test } from "bun:test";
|
|
5
|
+
import { createHash } from "node:crypto";
|
|
6
|
+
|
|
7
|
+
import { grant, principalOf } from "@niwa-labs/core";
|
|
8
|
+
import type { Address } from "@niwa-labs/core";
|
|
9
|
+
import { connect, createNiwa, connectAsOwner, tempHome } from "@niwa-labs/testing";
|
|
10
|
+
import type { NiwaApi } from "@niwa-labs/testing";
|
|
11
|
+
|
|
12
|
+
import { Attested, EvidenceRefusal, evidence, evidenceAttest, evidenceCovers, evidenceList, readAttestations } from "../src/index.ts";
|
|
13
|
+
import type { EvidenceOptions } from "../src/index.ts";
|
|
14
|
+
|
|
15
|
+
const sha = (word: string) => createHash("sha1").update(word).digest("hex");
|
|
16
|
+
const PR = "gitlab.example.com/acme/billing/pr/7";
|
|
17
|
+
const source = sha("head-1");
|
|
18
|
+
const target = sha("main-1");
|
|
19
|
+
|
|
20
|
+
const stops: Array<() => Promise<void>> = [];
|
|
21
|
+
afterEach(async () => {
|
|
22
|
+
for (const stop of stops.splice(0).reverse()) await stop();
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
async function served(options: EvidenceOptions = {}) {
|
|
26
|
+
const home = await tempHome();
|
|
27
|
+
const niwa = createNiwa({ home: home.path });
|
|
28
|
+
niwa.use(evidence(options));
|
|
29
|
+
await niwa.serve();
|
|
30
|
+
stops.push(async () => {
|
|
31
|
+
await niwa.close();
|
|
32
|
+
await home.cleanup();
|
|
33
|
+
});
|
|
34
|
+
const as = async (id: string, rules: string[] = []): Promise<NiwaApi> => {
|
|
35
|
+
const token = niwa.issueToken(principalOf("session", id), { grant: grant(["evidence.*", ...rules]) });
|
|
36
|
+
const client = await connect({ home: home.path, id: `session:${id}`, token });
|
|
37
|
+
stops.push(() => client.close());
|
|
38
|
+
return client;
|
|
39
|
+
};
|
|
40
|
+
const owner = async (): Promise<NiwaApi> => {
|
|
41
|
+
const client = await connectAsOwner(home.path);
|
|
42
|
+
stops.push(() => client.close());
|
|
43
|
+
return client;
|
|
44
|
+
};
|
|
45
|
+
return { niwa, as, owner };
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const mergeResult = (targetSha: string, pipelineKind: "merge-result" | "train" = "merge-result") => ({
|
|
49
|
+
kind: "ci" as const,
|
|
50
|
+
at: "merge-result" as const,
|
|
51
|
+
sourceSha: source,
|
|
52
|
+
targetSha,
|
|
53
|
+
mergeSha: sha(`merge-${targetSha}`),
|
|
54
|
+
pipeline: 501,
|
|
55
|
+
pipelineKind,
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
test("the author of an attestation is the caller the transport bound, and a payload cannot name another", async () => {
|
|
59
|
+
const { as, owner } = await served();
|
|
60
|
+
const ci = await as("ci-runner");
|
|
61
|
+
expect(await ci.call(evidenceAttest, { subject: PR, claim: mergeResult(target) })).toMatchObject({ author: { kind: "client", id: "session:ci-runner" } });
|
|
62
|
+
expect(await (await owner()).call(evidenceAttest, { subject: PR, claim: { kind: "verdict", name: "gates", outcome: "pass", sha: source } })).toMatchObject({
|
|
63
|
+
author: { kind: "owner" },
|
|
64
|
+
});
|
|
65
|
+
await expect(ci.call(evidenceAttest, { subject: PR, claim: mergeResult(target), author: { kind: "owner" } } as never)).rejects.toThrow();
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
test("a caller that stands for nobody cannot attest", async () => {
|
|
69
|
+
const { niwa } = await served();
|
|
70
|
+
await expect(niwa.call(evidenceAttest, { subject: PR, claim: mergeResult(target) })).rejects.toThrow(/author/);
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
test("a green merge result covers the pair of commits it ran on", async () => {
|
|
74
|
+
const { as } = await served();
|
|
75
|
+
const ci = await as("ci-runner");
|
|
76
|
+
const { id } = await ci.call(evidenceAttest, { subject: PR, claim: mergeResult(target, "train") });
|
|
77
|
+
const requirement = { kind: "ci" as const, at: "merge-result" as const, subject: PR, sourceSha: source, targetSha: target };
|
|
78
|
+
expect(await ci.call(evidenceCovers, { requirement })).toEqual({ covered: true, by: [id] });
|
|
79
|
+
expect(await ci.call(evidenceCovers, { requirement: { ...requirement, subject: `${PR}0` } })).toEqual({ covered: false, by: [], why: "none" });
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
test("a merge result stops covering when the target branch moved", async () => {
|
|
83
|
+
const { as } = await served();
|
|
84
|
+
const ci = await as("ci-runner");
|
|
85
|
+
await ci.call(evidenceAttest, { subject: PR, claim: mergeResult(target) });
|
|
86
|
+
const moved = { kind: "ci" as const, at: "merge-result" as const, subject: PR, sourceSha: source, targetSha: sha("main-2") };
|
|
87
|
+
expect(await ci.call(evidenceCovers, { requirement: moved })).toEqual({ covered: false, by: [], why: "target-moved" });
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
test("an ordinary pipeline of the head is not a merge result, though it covers the head", async () => {
|
|
91
|
+
const { as } = await served();
|
|
92
|
+
const ci = await as("ci-runner");
|
|
93
|
+
const { id } = await ci.call(evidenceAttest, { subject: PR, claim: { kind: "ci", at: "head", sha: source, pipeline: 500 } });
|
|
94
|
+
const merge = { kind: "ci" as const, at: "merge-result" as const, subject: PR, sourceSha: source, targetSha: target };
|
|
95
|
+
expect(await ci.call(evidenceCovers, { requirement: merge })).toEqual({ covered: false, by: [], why: "not-merge-result" });
|
|
96
|
+
expect(await ci.call(evidenceCovers, { requirement: { kind: "ci", at: "head", subject: PR, sha: source } })).toEqual({ covered: true, by: [id] });
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
test("a merge result cannot be attested of a pipeline kind that is not one", async () => {
|
|
100
|
+
const { as } = await served();
|
|
101
|
+
const ci = await as("ci-runner");
|
|
102
|
+
await expect(ci.call(evidenceAttest, { subject: PR, claim: { ...mergeResult(target), pipelineKind: "head" } as never })).rejects.toThrow();
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
test("a verdict covers its commit unless its author is excluded or a later one failed", async () => {
|
|
106
|
+
const { as } = await served();
|
|
107
|
+
const author = await as("patch-author");
|
|
108
|
+
const reviewer = await as("reviewer");
|
|
109
|
+
const verdict = (outcome: "pass" | "fail") => ({ subject: PR, claim: { kind: "verdict" as const, name: "gates", outcome, sha: source } });
|
|
110
|
+
const requirement = { kind: "verdict" as const, subject: PR, name: "gates", sha: source, notBy: [{ kind: "client" as const, id: "session:patch-author" }] };
|
|
111
|
+
await author.call(evidenceAttest, verdict("pass"));
|
|
112
|
+
expect(await reviewer.call(evidenceCovers, { requirement })).toEqual({ covered: false, by: [], why: "excluded-author" });
|
|
113
|
+
const { id } = await reviewer.call(evidenceAttest, verdict("pass"));
|
|
114
|
+
expect(await reviewer.call(evidenceCovers, { requirement })).toEqual({ covered: true, by: [id] });
|
|
115
|
+
await reviewer.call(evidenceAttest, verdict("fail"));
|
|
116
|
+
expect(await reviewer.call(evidenceCovers, { requirement })).toEqual({ covered: false, by: [], why: "failed" });
|
|
117
|
+
expect(await reviewer.call(evidenceCovers, { requirement: { ...requirement, sha: sha("other") } })).toEqual({ covered: false, by: [], why: "none" });
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
test("the attestations of a subject are listed with their authors", async () => {
|
|
121
|
+
const { as } = await served();
|
|
122
|
+
const ci = await as("ci-runner");
|
|
123
|
+
await ci.call(evidenceAttest, { subject: PR, claim: mergeResult(target) });
|
|
124
|
+
await ci.call(evidenceAttest, { subject: "plan/rev-1/node-1", claim: { kind: "verdict", name: "go", outcome: "pass", sha: source } });
|
|
125
|
+
const { items } = await ci.call(evidenceList, { subject: PR });
|
|
126
|
+
expect(items).toEqual([expect.objectContaining({ subject: PR, author: { kind: "client", id: "session:ci-runner" } })]);
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
const verdictClaim = (outcome: "pass" | "fail") => ({ kind: "verdict" as const, name: "gates", outcome, sha: source });
|
|
130
|
+
|
|
131
|
+
test("an attestation written straight to the journal is attributed to the caller the host recorded, not to its payload", async () => {
|
|
132
|
+
const { as } = await served();
|
|
133
|
+
const forger = await as("forger", ["emit:evidence.attested"]);
|
|
134
|
+
const reviewer = await as("reviewer");
|
|
135
|
+
const claim = verdictClaim("pass");
|
|
136
|
+
await forger.emit(Attested, { subject: PR, claim, author: { kind: "client", id: "session:reviewer" } });
|
|
137
|
+
const requirement = { kind: "verdict" as const, subject: PR, name: "gates", sha: source };
|
|
138
|
+
expect(await reviewer.call(evidenceCovers, { requirement })).toEqual({ covered: false, by: [], why: "none" });
|
|
139
|
+
expect((await reviewer.call(evidenceList, {})).items).toEqual([]);
|
|
140
|
+
// The same write, naming its true author, is an attestation like any other.
|
|
141
|
+
const honest = await forger.emit(Attested, { subject: PR, claim, author: { kind: "client", id: "session:forger" } });
|
|
142
|
+
expect(await reviewer.call(evidenceCovers, { requirement })).toEqual({ covered: true, by: [honest.id] });
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
test("a merge result of an earlier pipeline does not cover once another pipeline is the selected one", async () => {
|
|
146
|
+
const { as } = await served();
|
|
147
|
+
const ci = await as("ci-runner");
|
|
148
|
+
const { id } = await ci.call(evidenceAttest, { subject: PR, claim: mergeResult(target) });
|
|
149
|
+
await ci.call(evidenceAttest, { subject: PR, claim: { kind: "ci", at: "head", sha: source, pipeline: 502 } });
|
|
150
|
+
const requirement = { kind: "ci" as const, at: "merge-result" as const, subject: PR, sourceSha: source, targetSha: target };
|
|
151
|
+
expect(await ci.call(evidenceCovers, { requirement: { ...requirement, pipeline: 502 } })).toEqual({ covered: false, by: [], why: "not-merge-result" });
|
|
152
|
+
expect(await ci.call(evidenceCovers, { requirement: { ...requirement, pipeline: 501 } })).toEqual({ covered: true, by: [id] });
|
|
153
|
+
expect(await ci.call(evidenceCovers, { requirement: { ...requirement, pipeline: 503 } })).toEqual({ covered: false, by: [], why: "none" });
|
|
154
|
+
expect(await ci.call(evidenceCovers, { requirement: { ...requirement, targetSha: sha("main-2"), pipeline: 501 } })).toEqual({ covered: false, by: [], why: "target-moved" });
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
test("a verdict names only the passing verdict that stands, not one a later failure superseded", async () => {
|
|
158
|
+
const { as } = await served();
|
|
159
|
+
const reviewer = await as("reviewer");
|
|
160
|
+
await reviewer.call(evidenceAttest, { subject: PR, claim: verdictClaim("pass") });
|
|
161
|
+
await reviewer.call(evidenceAttest, { subject: PR, claim: verdictClaim("fail") });
|
|
162
|
+
const { id } = await reviewer.call(evidenceAttest, { subject: PR, claim: verdictClaim("pass") });
|
|
163
|
+
const requirement = { kind: "verdict" as const, subject: PR, name: "gates", sha: source };
|
|
164
|
+
expect(await reviewer.call(evidenceCovers, { requirement })).toEqual({ covered: true, by: [id] });
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
test("an excluded author is compared as a structured address, not as its display text", async () => {
|
|
168
|
+
// Both sessions read "session a/b/c" as text.
|
|
169
|
+
const bySession = (caller: { kind: string; principal?: { id: string } }): Address | undefined => {
|
|
170
|
+
if (caller.kind !== "client" || caller.principal === undefined) return undefined;
|
|
171
|
+
const [harness = "", id = ""] = caller.principal.id.split("|");
|
|
172
|
+
return { kind: "session", harness, id };
|
|
173
|
+
};
|
|
174
|
+
const { as } = await served({ bind: bySession });
|
|
175
|
+
const wrong = await as("a/b|c");
|
|
176
|
+
const right = await as("a|b/c");
|
|
177
|
+
const { id } = await right.call(evidenceAttest, { subject: PR, claim: verdictClaim("pass") });
|
|
178
|
+
const requirement = {
|
|
179
|
+
kind: "verdict" as const,
|
|
180
|
+
subject: PR,
|
|
181
|
+
name: "gates",
|
|
182
|
+
sha: source,
|
|
183
|
+
notBy: [{ kind: "session" as const, harness: "a/b", id: "c" }],
|
|
184
|
+
};
|
|
185
|
+
expect(await wrong.call(evidenceCovers, { requirement })).toEqual({ covered: true, by: [id] });
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
test("an author bound by the composition stays excluded when its session is relaunched under a new token", async () => {
|
|
189
|
+
const bySession = (caller: { kind: string; principal?: { id: string } }): Address | undefined =>
|
|
190
|
+
caller.kind === "client" && caller.principal !== undefined ? { kind: "session", harness: "claude", id: caller.principal.id.split("@")[0] ?? "" } : undefined;
|
|
191
|
+
const { as } = await served({ bind: bySession });
|
|
192
|
+
const author = await as("patch-author@launch-1");
|
|
193
|
+
await author.call(evidenceAttest, { subject: PR, claim: verdictClaim("pass") });
|
|
194
|
+
const relaunched = await as("patch-author@launch-2");
|
|
195
|
+
const requirement = { kind: "verdict" as const, subject: PR, name: "gates", sha: source, notBy: [{ kind: "session" as const, harness: "claude", id: "patch-author" }] };
|
|
196
|
+
await relaunched.call(evidenceAttest, { subject: PR, claim: verdictClaim("pass") });
|
|
197
|
+
expect(await relaunched.call(evidenceCovers, { requirement })).toEqual({ covered: false, by: [], why: "excluded-author" });
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
test("a read with no journal is refused rather than answered as empty", () => {
|
|
201
|
+
expect(() => readAttestations(undefined, () => undefined, {})).toThrow(EvidenceRefusal);
|
|
202
|
+
expect(() => readAttestations(undefined, () => undefined, {})).toThrow(/journal/);
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
test("a commit id is exactly 40 or 64 hex characters, and a verdict name has one bound for a claim and a requirement", async () => {
|
|
206
|
+
const { as } = await served();
|
|
207
|
+
const ci = await as("ci-runner");
|
|
208
|
+
const claim = (at: string) => ({ kind: "verdict" as const, name: "gates", outcome: "pass" as const, sha: at });
|
|
209
|
+
await expect(ci.call(evidenceAttest, { subject: PR, claim: claim("a".repeat(41)) })).rejects.toThrow();
|
|
210
|
+
await expect(ci.call(evidenceAttest, { subject: PR, claim: claim("a".repeat(64)) })).resolves.toBeDefined();
|
|
211
|
+
const name = "n".repeat(101);
|
|
212
|
+
await expect(ci.call(evidenceCovers, { requirement: { kind: "verdict", subject: PR, name, sha: source } })).rejects.toThrow();
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
test("the attestations are listed a page at a time, in the order they were written", async () => {
|
|
216
|
+
const { as } = await served();
|
|
217
|
+
const ci = await as("ci-runner");
|
|
218
|
+
const ids: string[] = [];
|
|
219
|
+
for (let index = 0; index < 5; index += 1) ids.push((await ci.call(evidenceAttest, { subject: index % 2 === 0 ? PR : "plan/x", claim: { kind: "ci", at: "head", sha: source, pipeline: index + 1 } })).id);
|
|
220
|
+
const first = await ci.call(evidenceList, { limit: 2 });
|
|
221
|
+
expect(first.items.map((one) => one.id)).toEqual(ids.slice(0, 2));
|
|
222
|
+
expect(first.next).toBeDefined();
|
|
223
|
+
const second = await ci.call(evidenceList, { limit: 2, after: first.next });
|
|
224
|
+
expect(second.items.map((one) => one.id)).toEqual(ids.slice(2, 4));
|
|
225
|
+
const last = await ci.call(evidenceList, { limit: 2, after: second.next });
|
|
226
|
+
expect(last.items.map((one) => one.id)).toEqual(ids.slice(4));
|
|
227
|
+
expect(last.next).toBeUndefined();
|
|
228
|
+
const mine = await ci.call(evidenceList, { subject: PR, limit: 2 });
|
|
229
|
+
expect(mine.items.map((one) => one.id)).toEqual(ids.filter((_, index) => index === 0 || index === 2));
|
|
230
|
+
expect(mine.next).toBeDefined();
|
|
231
|
+
expect((await ci.call(evidenceList, { subject: PR, limit: 2, after: mine.next })).items.map((one) => one.id)).toEqual(ids.slice(4));
|
|
232
|
+
});
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// The query builder of the evidence records: what a script waits for when it waits for an attestation.
|
|
2
|
+
|
|
3
|
+
import { expect, test } from "bun:test";
|
|
4
|
+
|
|
5
|
+
import { resolveQuery } from "@niwa-labs/core";
|
|
6
|
+
|
|
7
|
+
import { Attested, attested } from "../src/records.ts";
|
|
8
|
+
|
|
9
|
+
const subject = "gitlab.example.com/acme/billing/pr/7";
|
|
10
|
+
|
|
11
|
+
test("the attestations about a subject are a query of their type, filtered on the subject", () => {
|
|
12
|
+
expect(attested(subject)).toEqual({ types: [Attested], filter: { subject } });
|
|
13
|
+
expect(resolveQuery(attested(subject)).types?.map(String)).toEqual(["evidence.attested"]);
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
test("a subject that is empty is refused when the query is made", () => {
|
|
17
|
+
expect(() => attested("")).toThrow();
|
|
18
|
+
});
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
// A workflow run attests as itself: its calls carry the run's principal, and the default binding
|
|
2
|
+
// makes that the author.
|
|
3
|
+
|
|
4
|
+
import { afterEach, expect, test } from "bun:test";
|
|
5
|
+
import { writeFileSync } from "node:fs";
|
|
6
|
+
import { join } from "node:path";
|
|
7
|
+
|
|
8
|
+
import { record } from "@niwa-labs/core";
|
|
9
|
+
import { BUILTIN_WORKFLOW, plugin } from "@niwa-labs/plugin";
|
|
10
|
+
import { createNiwa, eventually, tempDir, tempHome, workflow } from "@niwa-labs/testing";
|
|
11
|
+
import { z } from "zod";
|
|
12
|
+
|
|
13
|
+
import { Attested, evidence } from "../src/index.ts";
|
|
14
|
+
|
|
15
|
+
const Go = record("probe.go", z.object({ sha: z.string() }));
|
|
16
|
+
|
|
17
|
+
const stops: Array<() => Promise<void>> = [];
|
|
18
|
+
afterEach(async () => {
|
|
19
|
+
for (const stop of stops.splice(0)) await stop();
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
test("an attestation made by a workflow run has the run as its author", async () => {
|
|
23
|
+
const home = await tempHome();
|
|
24
|
+
const file = join(await tempDir("probe"), "attest.ts");
|
|
25
|
+
writeFileSync(
|
|
26
|
+
file,
|
|
27
|
+
`export default workflow({ on: ["probe.go"], uses: ["evidence.attest"] }, async ({ data }) => {
|
|
28
|
+
await call("evidence.attest", { subject: "plan/rev-1/node-1", claim: { kind: "verdict", name: "go", outcome: "pass", sha: data.sha } }, { label: "attest" });
|
|
29
|
+
});
|
|
30
|
+
`,
|
|
31
|
+
);
|
|
32
|
+
const probe = plugin("probe", (api) => {
|
|
33
|
+
api.declare(Go);
|
|
34
|
+
api.offer(BUILTIN_WORKFLOW, { name: "attest", file, description: "Attest on every go", triggers: [Go] });
|
|
35
|
+
});
|
|
36
|
+
const niwa = createNiwa({ home: home.path });
|
|
37
|
+
niwa.use(evidence(), probe, workflow());
|
|
38
|
+
await niwa.serve();
|
|
39
|
+
stops.push(async () => {
|
|
40
|
+
await niwa.close();
|
|
41
|
+
await home.cleanup();
|
|
42
|
+
});
|
|
43
|
+
await eventually(async () => ((await niwa.call("workflow.installation.list" as never, {} as never)) as { items: unknown[] }).items.length === 1, 20_000, "not installed");
|
|
44
|
+
await niwa.emit(Go, { sha: "a".repeat(40) });
|
|
45
|
+
await eventually(async () => (await niwa.records.read({ types: [Attested.name] })).length === 1, 20_000, "nothing was attested");
|
|
46
|
+
const [attested] = await niwa.records.read({ types: [Attested.name] });
|
|
47
|
+
const runs = await niwa.records.read({ types: ["workflow.run.started"] });
|
|
48
|
+
const run = (runs[0]?.data as { run?: string } | undefined)?.run;
|
|
49
|
+
expect(run).toBeDefined();
|
|
50
|
+
expect((attested?.data as { author: unknown }).author).toEqual({ kind: "client", id: `run:${String(run)}` });
|
|
51
|
+
}, 60_000);
|