@geoqiao/pi-ask 1.1.0

package/src/state/normalize.ts

@@ -0,0 +1,326 @@
+import type {
+	AskOption,
+	AskParams,
+	AskQuestion,
+	AskQuestionInput,
+	AskValidationIssue,
+} from "../types.ts";
+
+interface IssueCollector {
+	add: (path: string, message: string) => void;
+	issues: AskValidationIssue[];
+}
+
+interface ValidationOptions {
+	allowFreeform?: boolean;
+	presentSingleAsMulti?: boolean;
+}
+
+export function normalizeQuestions(
+	params: AskParams,
+	options: ValidationOptions = {}
+): AskQuestion[] {
+	const issues = collectValidationIssues(params, options);
+	if (issues.length > 0) {
+		throw new Error(issues[0]?.message ?? "Invalid ask_user payload");
+	}
+	return params.questions.map((question, index) =>
+		normalizeQuestion(question, index, options)
+	);
+}
+
+export function collectValidationIssues(
+	params: AskParams,
+	options: ValidationOptions = {}
+): AskValidationIssue[] {
+	const collector = createIssueCollector();
+	validateQuestions(params.questions, collector, options);
+	return collector.issues;
+}
+
+function normalizeQuestion(
+	question: AskQuestionInput,
+	index: number,
+	options: ValidationOptions = {}
+): AskQuestion {
+	const requestedType = normalizeQuestionType(question.type);
+	const presentedType =
+		options.presentSingleAsMulti && requestedType === "single"
+			? "multi"
+			: requestedType;
+	return {
+		id: question.id.trim(),
+		label: question.label?.trim() || `Q${index + 1}`,
+		prompt: question.prompt.trim(),
+		type: presentedType,
+		...(presentedType === requestedType
+			? {}
+			: { requestedType, presentedType }),
+		required: question.required ?? false,
+		options: question.options.map(normalizeOption),
+	};
+}
+
+function normalizeOption(option: AskOption): AskOption {
+	return {
+		value: option.value.trim(),
+		label: option.label.trim(),
+		description: option.description?.trim(),
+		preview: option.preview?.trim(),
+		...(option.freeform ? { freeform: true } : {}),
+	};
+}
+
+function validateQuestions(
+	questions: AskParams["questions"],
+	collector: IssueCollector,
+	options: ValidationOptions
+) {
+	if (questions.length === 0) {
+		collector.add("questions", "At least one question is required");
+		return;
+	}
+
+	const questionIds = new Set<string>();
+	for (const [questionIndex, question] of questions.entries()) {
+		validateQuestion(question, questionIndex, questionIds, collector, options);
+	}
+}
+
+function validateQuestion(
+	question: AskQuestionInput,
+	questionIndex: number,
+	questionIds: Set<string>,
+	collector: IssueCollector,
+	options: ValidationOptions
+) {
+	const questionNumber = questionIndex + 1;
+	const questionPath = `questions[${questionIndex}]`;
+	const questionId = question.id?.trim();
+	const questionType = normalizeQuestionType(question.type);
+
+	validateQuestionType(
+		question.type,
+		questionNumber,
+		collector,
+		`${questionPath}.type`
+	);
+	assertRequired(
+		questionId,
+		collector,
+		`${questionPath}.id`,
+		`Question ${questionNumber}: id is required`
+	);
+	assertUnique(
+		questionIds,
+		questionId,
+		collector,
+		`${questionPath}.id`,
+		`Question ${questionNumber}: duplicate question id "${questionId}"`
+	);
+	assertOptionalText(
+		question.label,
+		collector,
+		`${questionPath}.label`,
+		`Question ${questionNumber}: label must not be empty`
+	);
+	assertRequired(
+		question.prompt?.trim(),
+		collector,
+		`${questionPath}.prompt`,
+		`Question ${questionNumber}: prompt is required`
+	);
+	assertHasItems(
+		question.options,
+		collector,
+		`${questionPath}.options`,
+		`Question ${questionNumber}: at least one option is required`
+	);
+
+	validateFreeformOptions(
+		question.options,
+		questionNumber,
+		collector,
+		`${questionPath}.options`,
+		options
+	);
+
+	const optionValues = new Set<string>();
+	for (const [optionIndex, option] of question.options.entries()) {
+		validateOption(
+			option,
+			optionIndex,
+			optionValues,
+			questionNumber,
+			questionType,
+			collector,
+			`${questionPath}.options[${optionIndex}]`
+		);
+	}
+}
+
+function validateFreeformOptions(
+	options: AskOption[],
+	questionNumber: number,
+	collector: IssueCollector,
+	path: string,
+	validationOptions: ValidationOptions
+) {
+	const freeformCount = options.filter((option) => option.freeform).length;
+	if (freeformCount === 0) {
+		return;
+	}
+	if (!validationOptions.allowFreeform) {
+		collector.add(
+			path,
+			`Question ${questionNumber}: freeform options are only supported for /answer forms`
+		);
+		return;
+	}
+	if (freeformCount > 1 || options.length > 1) {
+		collector.add(
+			path,
+			`Question ${questionNumber}: freeform options must be the only option`
+		);
+	}
+}
+
+function validateOption(
+	option: AskOption,
+	optionIndex: number,
+	optionValues: Set<string>,
+	questionNumber: number,
+	questionType: AskQuestion["type"],
+	collector: IssueCollector,
+	optionPath: string
+) {
+	const optionNumber = optionIndex + 1;
+	const prefix = `Question ${questionNumber}, option ${optionNumber}`;
+	const optionValue = option.value?.trim();
+	const optionPreview = option.preview?.trim();
+
+	assertRequired(
+		optionValue,
+		collector,
+		`${optionPath}.value`,
+		`${prefix}: value is required`
+	);
+	assertUnique(
+		optionValues,
+		optionValue,
+		collector,
+		`${optionPath}.value`,
+		`${prefix}: duplicate option value "${optionValue}"`
+	);
+	assertRequired(
+		option.label?.trim(),
+		collector,
+		`${optionPath}.label`,
+		`${prefix}: label is required`
+	);
+	assertOptionalText(
+		option.description,
+		collector,
+		`${optionPath}.description`,
+		`${prefix}: description must not be empty`
+	);
+	assertOptionalText(
+		option.preview,
+		collector,
+		`${optionPath}.preview`,
+		`${prefix}: preview must not be empty`
+	);
+	if (questionType === "preview") {
+		assertRequired(
+			optionPreview,
+			collector,
+			`${optionPath}.preview`,
+			`${prefix}: preview questions require preview text for every option; add preview text or use type "single" instead`
+		);
+	}
+}
+
+function normalizeQuestionType(
+	value: AskQuestionInput["type"]
+): AskQuestion["type"] {
+	return value === "multi" || value === "preview" ? value : "single";
+}
+
+function validateQuestionType(
+	value: AskQuestionInput["type"],
+	questionNumber: number,
+	collector: IssueCollector,
+	path: string
+) {
+	if (
+		value !== undefined &&
+		value !== "single" &&
+		value !== "multi" &&
+		value !== "preview"
+	) {
+		collector.add(
+			path,
+			`Question ${questionNumber}: invalid type ${JSON.stringify(value)}; expected "single", "multi", or "preview"`
+		);
+	}
+}
+
+function assertHasItems(
+	items: unknown[],
+	collector: IssueCollector,
+	path: string,
+	message: string
+) {
+	if (items.length === 0) {
+		collector.add(path, message);
+	}
+}
+
+function assertRequired(
+	value: string | undefined,
+	collector: IssueCollector,
+	path: string,
+	message: string
+) {
+	if (!value) {
+		collector.add(path, message);
+	}
+}
+
+function assertOptionalText(
+	value: string | undefined,
+	collector: IssueCollector,
+	path: string,
+	message: string
+) {
+	if (value !== undefined && !value.trim()) {
+		collector.add(path, message);
+	}
+}
+
+function assertUnique(
+	seen: Set<string>,
+	value: string | undefined,
+	collector: IssueCollector,
+	path: string,
+	message: string
+) {
+	if (!value) {
+		return;
+	}
+	if (seen.has(value)) {
+		collector.add(path, message);
+		return;
+	}
+	seen.add(value);
+}
+
+function createIssueCollector(): IssueCollector {
+	const issues: AskValidationIssue[] = [];
+	return {
+		issues,
+		add(path, message) {
+			issues.push({ path, message });
+		},
+	};
+}

package/src/state/question-type.ts

@@ -0,0 +1,128 @@
+import type { AskQuestionType, AskState, AskStateAnswer } from "../types.ts";
+import { isAnswerEmpty } from "./answers.ts";
+import { getAnswer, getCurrentQuestion, isSubmitTab } from "./selectors.ts";
+
+export interface QuestionTypeChangeResult {
+	needsConfirmation: boolean;
+	notice?: string;
+	state: AskState;
+}
+
+export function cycleCurrentQuestionType(
+	state: AskState,
+	options: { confirmed?: boolean } = {}
+): QuestionTypeChangeResult {
+	if (isSubmitTab(state)) {
+		return { needsConfirmation: false, state };
+	}
+
+	const question = getCurrentQuestion(state);
+	if (!question) {
+		return { needsConfirmation: false, state };
+	}
+
+	const nextType = getNextQuestionType(question);
+	if (nextType === question.type) {
+		return { needsConfirmation: false, state };
+	}
+
+	const answer = getAnswer(state, question.id);
+	const requiresConfirmation =
+		nextType === "single" && countCommittedAnswers(answer) > 1;
+	if (requiresConfirmation && !options.confirmed) {
+		return {
+			needsConfirmation: true,
+			notice:
+				"Switching to single-select will clear selected options for this question. Press the type key again to confirm.",
+			state,
+		};
+	}
+
+	return {
+		needsConfirmation: false,
+		notice: getQuestionTypeChangeNotice(question.type, nextType),
+		state: setQuestionType(state, question.id, nextType, {
+			clearSelectedOptions: requiresConfirmation,
+		}),
+	};
+}
+
+function getNextQuestionType(question: {
+	requestedType?: AskQuestionType;
+	type: AskQuestionType;
+}): AskQuestionType {
+	const requestedType = question.requestedType ?? question.type;
+	if (requestedType === "preview") {
+		return question.type === "preview" ? "multi" : "preview";
+	}
+	switch (question.type) {
+		case "single":
+			return "multi";
+		case "multi":
+			return "single";
+		case "preview":
+			return "multi";
+		default:
+			return "multi";
+	}
+}
+
+function countCommittedAnswers(answer: AskStateAnswer | undefined): number {
+	if (!answer) {
+		return 0;
+	}
+	return (
+		answer.selected.length +
+		(answer.customSelected && answer.customText?.trim() ? 1 : 0)
+	);
+}
+
+function setQuestionType(
+	state: AskState,
+	questionId: string,
+	type: AskQuestionType,
+	options: { clearSelectedOptions: boolean }
+): AskState {
+	const questions = state.questions.map((question) => {
+		if (question.id !== questionId) {
+			return question;
+		}
+		const requestedType = question.requestedType ?? question.type;
+		return {
+			...question,
+			type,
+			requestedType,
+			presentedType: type === requestedType ? undefined : type,
+		};
+	});
+
+	const currentAnswer = state.answers[questionId];
+	if (!(options.clearSelectedOptions && currentAnswer)) {
+		return { ...state, questions };
+	}
+
+	const nextAnswer = {
+		...currentAnswer,
+		customSelected: currentAnswer.customText?.trim() ? true : undefined,
+		selected: [],
+	};
+	const answers = { ...state.answers };
+	if (isAnswerEmpty(nextAnswer)) {
+		delete answers[questionId];
+	} else {
+		answers[questionId] = nextAnswer;
+	}
+
+	return {
+		...state,
+		questions,
+		answers,
+	};
+}
+
+function getQuestionTypeChangeNotice(
+	from: AskQuestionType,
+	to: AskQuestionType
+): string {
+	return `Question type changed from ${from} to ${to}.`;
+}

package/src/state/result.ts

@@ -0,0 +1,263 @@
+import {
+	CANCELLED_SUMMARY,
+	ELABORATED_SUMMARY,
+	ELABORATION_INSTRUCTION,
+	SUBMITTED_SUMMARY,
+} from "../constants/text.ts";
+import { formatElaborationLines, formatResultLines } from "../result-format.ts";
+import type {
+	AskContinuationPayload,
+	AskElaborationPayload,
+	AskResult,
+	AskResultAnswer,
+	AskState,
+	AskStateAnswer,
+} from "../types.ts";
+import {
+	cloneResultAnswer,
+	getExtraOptionNotes,
+	hasAnswerNotes,
+	isAnswerAnswered,
+	isAnswerEmpty,
+	isOptionSelected,
+	isResultAnswerCommitted,
+	isResultAnswerEmpty,
+	serializeAnswer,
+} from "./answers.ts";
+import { getQuestionOptionByValue } from "./selectors.ts";
+
+export type ReviewAnswer = AskResult["answers"][string] & {
+	extraOptionNotes?: Array<{
+		label: string;
+		note: string;
+	}>;
+};
+
+export function toAskResult(state: AskState): AskResult {
+	const answers = Object.fromEntries(
+		Object.entries(state.answers)
+			.map(
+				([questionId, answer]) => [questionId, serializeAnswer(answer)] as const
+			)
+			.filter(([, answer]) =>
+				state.mode === "elaborate"
+					? isResultAnswerCommitted(answer)
+					: !isResultAnswerEmpty(answer)
+			)
+	);
+
+	return {
+		title: state.title,
+		cancelled: state.cancelled,
+		mode: state.mode,
+		questions: state.questions.map((question) => ({
+			id: question.id,
+			label: question.label,
+			prompt: question.prompt,
+			type: question.requestedType ?? question.type,
+			...(question.presentedType &&
+			question.presentedType !== question.requestedType
+				? { presentedType: question.presentedType }
+				: {}),
+		})),
+		answers,
+		continuation:
+			state.mode === "elaborate"
+				? serializeContinuation(state, answers)
+				: undefined,
+		elaboration:
+			state.mode === "elaborate" ? serializeElaboration(state) : undefined,
+	};
+}
+
+export function summarizeResult(result: AskResult): string {
+	if (result.cancelled) {
+		return CANCELLED_SUMMARY;
+	}
+	if (result.mode === "elaborate") {
+		const lines = formatElaborationLines(result, { mode: "summary" });
+		return lines.join("\n") || ELABORATED_SUMMARY;
+	}
+
+	const lines = formatResultLines(result, { mode: "summary" });
+	return lines.join("\n") || SUBMITTED_SUMMARY;
+}
+
+export function hasAnswerContent(state: AskState, questionId: string): boolean {
+	const answer = state.answers[questionId];
+	return !!answer && !isAnswerEmpty(answer);
+}
+
+function serializeContinuation(
+	state: AskState,
+	answers: AskResult["answers"]
+): AskContinuationPayload {
+	const affectedQuestionIds: string[] = [];
+	const preservedAnswers: AskContinuationPayload["preservedAnswers"] = {};
+	const questionStates: AskContinuationPayload["questionStates"] = {};
+
+	for (const question of state.questions) {
+		const answer = state.answers[question.id];
+		const hasClarificationNeed = hasAnswerNotes(answer);
+		const committedAnswer = answers[question.id];
+		const answered = !!committedAnswer;
+
+		if (hasClarificationNeed) {
+			affectedQuestionIds.push(question.id);
+			questionStates[question.id] = { status: "needs_clarification" };
+			continue;
+		}
+
+		if (answered) {
+			preservedAnswers[question.id] = cloneResultAnswer(committedAnswer);
+			questionStates[question.id] = { status: "answered" };
+			continue;
+		}
+
+		questionStates[question.id] = { status: "unanswered" };
+	}
+
+	return {
+		affectedQuestionIds,
+		preservedAnswers,
+		questionStates,
+		strategy: "refine_only",
+	};
+}
+
+function serializeElaboration(state: AskState): AskElaborationPayload {
+	const items = state.questions.flatMap((question) =>
+		serializeElaborationItemsForQuestion(question, state.answers[question.id])
+	);
+
+	return {
+		instruction: ELABORATION_INSTRUCTION,
+		nextAction: "clarify_then_reask",
+		items,
+	};
+}
+
+function serializeElaborationItemsForQuestion(
+	question: AskState["questions"][number],
+	answer: AskStateAnswer | undefined
+): AskElaborationPayload["items"] {
+	if (!(answer && hasAnswerNotes(answer))) {
+		return [];
+	}
+
+	const questionContext = createElaborationQuestionContext(question);
+	const serializedAnswer = toCommittedResultAnswer(answer);
+	const answered = isAnswerAnswered(answer);
+	const items: AskElaborationPayload["items"] = [];
+
+	if (answer.note) {
+		items.push({
+			target: { kind: "question" },
+			question: questionContext,
+			answered,
+			answer: serializedAnswer,
+			note: answer.note,
+		});
+	}
+
+	for (const [value, note] of Object.entries(answer.optionNotes ?? {})) {
+		const option = getQuestionOptionByValue(question, value);
+		if (!(option && note)) {
+			continue;
+		}
+
+		items.push({
+			target: {
+				kind: "option",
+				optionValue: value,
+			},
+			question: questionContext,
+			option: cloneOption(option),
+			selected: isOptionSelected(answer, value),
+			answered,
+			answer: serializedAnswer,
+			note,
+		});
+	}
+
+	return items;
+}
+
+function createElaborationQuestionContext(
+	question: AskState["questions"][number]
+) {
+	return {
+		id: question.id,
+		label: question.label,
+		prompt: question.prompt,
+		type: question.requestedType ?? question.type,
+		...(question.presentedType &&
+		question.presentedType !== question.requestedType
+			? { presentedType: question.presentedType }
+			: {}),
+		options: question.options.map(cloneOption),
+	};
+}
+
+function cloneOption(option: AskState["questions"][number]["options"][number]) {
+	return {
+		value: option.value,
+		label: option.label,
+		...(option.description ? { description: option.description } : {}),
+		...(option.preview ? { preview: option.preview } : {}),
+	};
+}
+
+function toCommittedResultAnswer(
+	answer: AskStateAnswer | undefined
+): AskResultAnswer | undefined {
+	if (!(answer && isAnswerAnswered(answer))) {
+		return;
+	}
+	return cloneResultAnswer(serializeAnswer(answer));
+}
+
+export function toReviewAnswer(
+	question: AskState["questions"][number],
+	answer: AskStateAnswer | undefined,
+	showAllNotes: boolean
+): ReviewAnswer | undefined {
+	if (!answer) {
+		return;
+	}
+
+	const serialized = serializeAnswer(answer);
+	const hasCommittedAnswer = isResultAnswerCommitted(serialized);
+	if (!showAllNotes) {
+		return hasCommittedAnswer ? serialized : undefined;
+	}
+
+	const extraOptionNotes = getExtraOptionNotes({
+		answer,
+		questionOptions: question.options,
+		selectedValues: serialized.values,
+	});
+	if (
+		!(hasCommittedAnswer || serialized.note) &&
+		extraOptionNotes.length === 0
+	) {
+		return;
+	}
+
+	return {
+		...serialized,
+		extraOptionNotes:
+			extraOptionNotes.length > 0 ? extraOptionNotes : undefined,
+	};
+}
+
+export function shouldRenderAnswersIndividually(answer: ReviewAnswer): boolean {
+	if (!answer.labels.length) {
+		return false;
+	}
+
+	return (
+		answer.labels.length > 1 ||
+		Boolean(answer.optionNotes && Object.keys(answer.optionNotes).length > 0)
+	);
+}