pi-roundtable 0.19.1 → 0.20.0

package/src/core/testing/surface-contract-questionnaire.ts

@@ -0,0 +1,192 @@
+import { describe, test } from "bun:test";
+import {
+	type AskSupport,
+	type Questionnaire,
+	type QuestionnaireAnswer,
+	shapeFor,
+} from "../interactions/questionnaire.ts";
+import type { SurfaceContractSubject } from "./surface-contract.ts";
+import {
+	ContractBroken,
+	expectThat,
+	nextPrompt,
+	type Running,
+	runCheck,
+	scopeOf,
+	seen,
+	until,
+} from "./surface-contract-support.ts";
+
+/** One check of the questionnaire part of the surface contract. */
+export interface QuestionnaireCheck {
+	name: string;
+	applies(subject: SurfaceContractSubject): boolean;
+	run(running: Running): Promise<void>;
+}
+
+/** The set the checks ask: two questions, the first with previews where the surface shows them. */
+function contractSet(asks: AskSupport): Questionnaire {
+	const preview = asks.previews ? { preview: "```\nlayout\n```" } : {};
+	const day = {
+		question: "Which day?",
+		header: "Day",
+		options: [
+			{ label: "Saturday", ...preview },
+			{ label: "Sunday", ...preview },
+		],
+		multi: false,
+		allowOther: true,
+	};
+	const food = {
+		question: "Which food?",
+		options: [{ label: "Rice" }, { label: "Noodles" }],
+		multi: true,
+		allowOther: false,
+	};
+	return shapeFor(
+		{ questions: asks.questions >= 2 ? [day, food] : [day] },
+		asks,
+	);
+}
+
+/** The person's prompts, once the surface has started; undefined where it declares no `asks`. */
+function questionnairePrompts(running: Running) {
+	const { surface, channel } = running.subject;
+	const prompts = surface.prompts?.(channel, scopeOf(running.subject));
+	if (!prompts?.asks || !prompts.questionnaire)
+		throw new ContractBroken(
+			"the subject answers questionnaires, but its prompts declare no asks",
+		);
+	return { prompts, asks: prompts.asks, ask: prompts.questionnaire };
+}
+
+const answerOf = (
+	set: Questionnaire,
+	asks: AskSupport,
+): QuestionnaireAnswer => ({
+	answers: set.questions.map((_, i) =>
+		i === 0 ? { choices: ["Sunday"] } : undefined,
+	),
+	...(asks.note ? { note: "thanks" } : {}),
+});
+
+const applies = (subject: SurfaceContractSubject) =>
+	subject.surface.prompts !== undefined &&
+	subject.answerQuestionnaire !== undefined;
+
+/**
+ * The questionnaire checks. They apply to a subject that gives `answerQuestionnaire`, which must declare `asks`;
+ * a surface that takes one question at a time gives none and is skipped.
+ */
+export const QUESTIONNAIRE_CHECKS: readonly QuestionnaireCheck[] = [
+	{
+		name: "a questionnaire resolves as the person answers it, keeps a blank question blank, and closes",
+		applies,
+		run: async (running) => {
+			const found = questionnairePrompts(running);
+			const answer = running.subject.answerQuestionnaire;
+			if (!answer) return;
+			const set = contractSet(found.asks);
+			const before = seen(running, "prompt").length;
+			const result = found.ask("Questions", set);
+			const id = await nextPrompt(running, before);
+			const given = answerOf(set, found.asks);
+			await answer(id, given, set);
+			const got = await result;
+			if (got === "pending" || got === undefined)
+				throw new ContractBroken(`the person's answers came back ${got}`);
+			expectThat(
+				JSON.stringify(got.answers.map((a) => a ?? null)) ===
+					JSON.stringify(given.answers.map((a) => a ?? null)),
+				`the answers came back as ${JSON.stringify(got.answers)}`,
+			);
+			expectThat(
+				got.note === given.note,
+				`the note came back as ${JSON.stringify(got.note)}`,
+			);
+			await until(
+				() =>
+					seen(running, "prompt_closed").some(
+						(o) => o.kind === "prompt_closed" && o.id === id,
+					),
+				"the answered questionnaire closes",
+			);
+		},
+	},
+	{
+		name: "a stopped turn's questionnaire resolves with no answer and closes",
+		applies,
+		run: async (running) => {
+			const found = questionnairePrompts(running);
+			const stop = new AbortController();
+			const before = seen(running, "prompt").length;
+			const result = found.ask(
+				"Questions",
+				contractSet(found.asks),
+				stop.signal,
+			);
+			const id = await nextPrompt(running, before);
+			stop.abort();
+			const got = await result;
+			expectThat(
+				got === undefined,
+				`a stopped turn's questionnaire got ${got}`,
+			);
+			await until(
+				() =>
+					seen(running, "prompt_closed").some(
+						(o) => o.kind === "prompt_closed" && o.id === id,
+					),
+				"the stopped questionnaire closes",
+			);
+		},
+	},
+	{
+		name: "another person cannot answer the person's questionnaire",
+		applies: (subject) =>
+			applies(subject) && subject.stranger?.answerQuestionnaire !== undefined,
+		run: async (running) => {
+			const found = questionnairePrompts(running);
+			const stranger = running.subject.stranger;
+			const answer = running.subject.answerQuestionnaire;
+			if (!answer || !stranger?.answerQuestionnaire) return;
+			await stranger.join?.();
+			const set = contractSet(found.asks);
+			const before = seen(running, "prompt").length;
+			let settled: unknown;
+			const result = found.ask("Questions", set).then((value) => {
+				settled = value;
+				return value;
+			});
+			const id = await nextPrompt(running, before);
+			await stranger.answerQuestionnaire(id, answerOf(set, found.asks), set);
+			await Bun.sleep(50);
+			expectThat(
+				settled === undefined,
+				"another person's answer settled the questionnaire",
+			);
+			await answer(id, answerOf(set, found.asks), set);
+			const own = await result;
+			expectThat(
+				own !== "pending" && own !== undefined,
+				`the person's answer came back ${own}`,
+			);
+		},
+	},
+];
+
+/**
+ * Registers only the questionnaire part of the contract, for a card layer without a chat around
+ * it. Internal: the published contract is `describeSurfaceContract`.
+ */
+export function describeQuestionnaireContract(
+	name: string,
+	make: () => Promise<SurfaceContractSubject>,
+): void {
+	describe(`${name} keeps the questionnaire contract`, () => {
+		for (const check of QUESTIONNAIRE_CHECKS)
+			test(check.name, async () => {
+				await runCheck(check, make);
+			});
+	});
+}

package/src/core/testing/surface-contract-support.ts

@@ -192,3 +192,25 @@ export async function namedApproverAnswers(running: Running): Promise<void> {
 		`the approval reported ${reported?.principalId} as its approver, not ${approver.principalId}`,
 	);
 }
+
+/** Runs one check on a fresh subject from `make`, starting and stopping its surface around it. */
+export async function runCheck(
+	check: {
+		applies?(subject: SurfaceContractSubject): boolean;
+		run(running: Running): Promise<void>;
+	},
+	make: () => Promise<SurfaceContractSubject>,
+): Promise<"passed" | "skipped"> {
+	const subject = await make();
+	const running: Running = { subject, delivered: [] };
+	try {
+		if (check.applies && !check.applies(subject)) return "skipped";
+		await subject.surface.start((message) => running.delivered.push(message));
+		await subject.join?.();
+		await check.run(running);
+		return "passed";
+	} finally {
+		await subject.close?.();
+		await subject.surface.stop?.();
+	}
+}

package/src/core/testing/surface-contract.ts

@@ -3,8 +3,13 @@ import type { ChatSurface } from "../contract/surface.ts";
 import { parseChannelKey } from "../contract/surface.ts";
 import type { TurnProgress } from "../domain/progress.ts";
 import type { Approval } from "../interactions/prompts.ts";
+import type {
+	Questionnaire,
+	QuestionnaireAnswer,
+} from "../interactions/questionnaire.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
+import { QUESTIONNAIRE_CHECKS } from "./surface-contract-questionnaire.ts";
 import {
 	answeredOnlyByThem,
 	approval,
@@ -13,6 +18,7 @@ import {
 	namedApproverAnswers,
 	nextPrompt,
 	type Running,
+	runCheck,
 	scopeOf,
 	seen,
 	speakerOf,
@@ -44,6 +50,12 @@ export interface SurfaceContractSubject {
 	observations(): readonly SurfaceObservation[];
 	/** The person answers an open approval; without it the prompt checks are skipped. */
 	answer?(prompt: string, approved: boolean): Promise<void>;
+	/** The person answers an open questionnaire, as shaped for `asks`; without it those checks are skipped. */
+	answerQuestionnaire?(
+		prompt: string,
+		answer: QuestionnaireAnswer,
+		questionnaire: Questionnaire,
+	): Promise<void>;
 	/**
 	 * The person as the speaker of the turns that ask them, given to `surface.prompts` as the
 	 * scope `promptScope(speaker, visibility)`; default an owner-tier speaker. Every approval the
@@ -85,6 +97,12 @@ export interface SurfaceContractAnswerer {
 	/** They join the surface, once it has started. */
 	join?(): Promise<void>;
 	answer(prompt: string, approved: boolean): Promise<void>;
+	/** They answer an open questionnaire; without it its stranger check is skipped. */
+	answerQuestionnaire?(
+		prompt: string,
+		answer: QuestionnaireAnswer,
+		questionnaire: Questionnaire,
+	): Promise<void>;
 }
 
 /** One way the subject broke the contract. */
@@ -401,26 +419,9 @@ const CHECKS: readonly Check[] = [
 			);
 		},
 	},
+	...QUESTIONNAIRE_CHECKS,
 ];
 
-async function runCheck(
-	check: Check,
-	make: () => Promise<SurfaceContractSubject>,
-): Promise<"passed" | "skipped"> {
-	const subject = await make();
-	const running: Running = { subject, delivered: [] };
-	try {
-		if (check.applies && !check.applies(subject)) return "skipped";
-		await subject.surface.start((message) => running.delivered.push(message));
-		await subject.join?.();
-		await check.run(running);
-		return "passed";
-	} finally {
-		await subject.close?.();
-		await subject.surface.stop?.();
-	}
-}
-
 /**
  * Runs the chat surface contract on fresh subjects from `make`, one per check, and returns the
  * checks the surface broke. `describeSurfaceContract` registers the same checks as tests.
@@ -449,7 +450,8 @@ export async function checkSurfaceContract(
  * too, and lets an approval above the person's tier there come back at once, shown to no one.
  * Where it can name approvers, an approval that does is answered by them, reported as the
  * approver, and not by the person or another person, and a private conversation's is answered by
- * its person alone, whoever the call names besides them. Each
+ * its person alone, whoever the call names besides them. A subject that gives
+ * `answerQuestionnaire` must declare `asks`, and then questionnaires keep the same rules. Each
  * check gets a fresh subject from `make`; a check for an optional part the surface lacks passes.
  */
 export function describeSurfaceContract(

package/src/index.ts

@@ -195,6 +195,7 @@ export type {
 	ApprovalOptions,
 	ApprovedBy,
 	AskOption,
+	AskSupport,
 	LateAnswer,
 	OwnerAnswer,
 	OwnerPrompts,
@@ -202,8 +203,18 @@ export type {
 	PromptScope,
 	Prompts,
 	PromptWait,
+	Questionnaire,
+	QuestionnaireAnswer,
 } from "./core/interactions/prompts.ts";
 export { promptScope, withdrawalNote } from "./core/interactions/prompts.ts";
+export {
+	checkAnswer,
+	checkQuestionnaireAnswer,
+	QUESTIONNAIRE_LIMITS,
+	SINGLE_QUESTION,
+	shapeFor,
+	validateQuestionnaire,
+} from "./core/interactions/questionnaire.ts";
 export type { JudgeModel } from "./core/judging/model-judge.ts";
 export type { LogEntry, LogFn, Logger } from "./core/log.ts";
 export type { ThinkingLevel, ThinkingSetting } from "./core/models.ts";