Files
mesh-catalog/modules/gitea/calls.ts
T
jschoubben 7f5f285b60 FORGE-3: a merge call says one merge-called, and the start says an unsaid one
Once its members are merged or refused the call says merge-called on
merge-called.<call> with its landed members (base and merge commit) and
its refused ones, and is kept said; a call that landed none says none. At
the start every call not said says it for what landed.

Builds: design 47 H §736, §766 (said again at the start); H-A-18, H-A-47 (said), H-A-71 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:45:27 +01:00

112 lines
5.8 KiB
TypeScript

// **The call is written before its first merge** (novox/hq design 47 H §766; H-A-18, H-A-47, H-A-71): before it merges
// anything, the forge module writes the call's key `call.<call>` in its own template state `calls` (the seat git's
// definition declares it): `by`, the bus account the tool runner proved, `at`, the members, each with its base `branch`
// and `state` judged, merged with its commit, or refused with why, and `said`, whether its `merge-called` was said. Each
// member is updated as it merges. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge
// module on each new call's write, oldest first, with no timer (H-A-47).
import { readFileSync } from "node:fs";
import type { State } from "@novox/mesh-sdk/state";
import {
callsByCallCallKey, mergeCalledSubject, parseCallsByCallCallKey, type Call, type CallMember, type MergeCalledEvent,
} from "@novox/mesh-delivery-contracts-git";
/** call-retention's default, in days (§766). */
export const CALL_RETENTION_DAYS = 30;
/** call-retention as the module's config file says it, in days; the default when it says none (mainrules.ts' form). */
export function callRetentionDays(env: NodeJS.ProcessEnv = process.env): number {
const file = env.MESH_GITEA_CONFIG_FILE;
if (!file) return CALL_RETENTION_DAYS;
try {
const v = Number((JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>)["call-retention"]);
return Number.isInteger(v) && v >= 1 ? v : CALL_RETENTION_DAYS;
} catch { return CALL_RETENTION_DAYS; }
}
/** One kept call with its id. */
export interface KeptCall extends Call {
call: string;
}
/** The state `calls`: one key per merge call. */
export class Calls {
constructor(private readonly st: State<unknown>, private readonly retentionDays: () => number = () => CALL_RETENTION_DAYS,
private readonly log: (line: string) => void = () => {}) {}
/** Every call kept, newest first. */
async all(): Promise<KeptCall[]> {
const out: KeptCall[] = [];
for (const key of await this.st.keys()) {
const parsed = parseCallsByCallCallKey(key);
if (!parsed) continue;
const e = await this.st.get(key);
if (e?.value) out.push({ ...(e.value as Call), call: parsed.call });
}
return out.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : a.call < b.call ? 1 : -1));
}
/** One call, or undefined. */
async get(call: string): Promise<KeptCall | undefined> {
const e = await this.st.get(callsByCallCallKey(call));
return e?.value ? { ...(e.value as Call), call } : undefined;
}
/** Writes a call. A new call (none kept under its key) first deletes the calls past call-retention, oldest first. */
async put(call: string, value: Call, now: Date = new Date()): Promise<void> {
if (!(await this.st.get(callsByCallCallKey(call)))?.value) await this.expire(now);
await this.st.put(callsByCallCallKey(call), value);
}
/** Deletes the calls whose `at` is past call-retention before now, oldest first; answers the calls deleted. */
async expire(now: Date): Promise<string[]> {
const before = now.getTime() - this.retentionDays() * 86_400_000;
const old = (await this.all()).filter((c) => (Date.parse(c.at) || 0) < before).reverse();
for (const c of old) await this.st.delete(callsByCallCallKey(c.call));
if (old.length) this.log(`${old.length} merge calls past ${this.retentionDays()} days deleted: ${old.map((c) => c.call).join(", ")}`);
return old.map((c) => c.call);
}
}
/** A kept member of a call. */
export const keptMember = (m: { repository: string; number: number; branch: string; head: string; state: CallMember["state"];
commit?: string; why?: string }): CallMember => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head,
state: m.state, ...(m.commit ? { commit: m.commit } : {}), ...(m.why ? { why: m.why } : {}) });
/** Says a seat event on its subject, under an id the bus keeps once. */
export type Say = (subject: string, body: unknown, id?: string) => Promise<void>;
/** The merge-called of a kept call (design 47 H §736, §767): its landed members, each with its base and merge commit, and its
* refused ones; undefined for a call that landed no member, which says none. */
export function mergeCalledOf(c: KeptCall): MergeCalledEvent | undefined {
const landed = c.members.filter((m) => m.state === "merged" && m.commit);
if (landed.length === 0) return undefined;
// A member judged and not merged (a stop mid-call) is in neither: its head is an untaken head (§740).
const refused = c.members.filter((m) => m.state === "refused");
return { call: c.call, by: c.by, account: c.account, at: c.at,
members: landed.map((m) => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head, commit: m.commit! })),
...(refused.length ? { refused: refused.map((m) => ({ repository: m.repository, number: m.number, why: m.why ?? "not merged" })) } : {}) };
}
/** Says a call's merge-called, when it landed a member; answers whether it said one. */
export async function sayCall(c: KeptCall, say: Say): Promise<boolean> {
const body = mergeCalledOf(c);
if (!body) return false;
await say(mergeCalledSubject(c.call), body, `merge-called.${c.call}`);
return true;
}
/** At the start (§766): every call whose event is not said says merge-called for what landed, and is kept said, so a stop
* between the last merge and the event loses nothing it recorded. Answers the calls said. */
export async function sayUnsaid(calls: Calls, say: Say, log: (line: string) => void = () => {}): Promise<string[]> {
const said: string[] = [];
for (const c of await calls.all()) {
if (c.said) continue;
if (await sayCall(c, say)) said.push(c.call);
const { call, ...value } = c;
await calls.put(call, { ...value, said: true });
}
if (said.length) log(`merge-called said again at the start for ${said.join(", ")}`);
return said;
}