Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions packages/core/question-block.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { describe, expect, test } from "bun:test";
import {
buildQuestionAnswerAnnotation,
canonicalQuestionAnswer,
formatQuestionAnswerText,
formatQuestionAnswersSection,
indexQuestionBlocks,
Expand Down Expand Up @@ -360,6 +361,86 @@ describe("plain-bullet choices keep their wrapped lines", () => {
});
});

// 0.28.2 pre-tag smoke: 0.28.1 read a wrapped plain bullet's first line as
// its label, so an answer saved then quotes that line. It must still show the
// choice it picked (and export as it), under the label 0.28.2 gives it.
describe("answers saved under an older label", () => {
const OLD_LABEL = '**One per session:** "ramos · cloud-3", "ramos · cloud-4". Each agent shows';
const index = indexQuestionBlocks([{ id: "b", type: "directive", directiveKind: "question", content: WRAPPED_PLAIN_BULLETS, startLine: 1 }]);
const q = index[0].question;
const saved: QuestionAnswer = { v: 1, key: q.key, kind: "single", prompt: q.prompt, selected: [OLD_LABEL] };

test("canonicalQuestionAnswer maps a 0.28.1 label to the current one", () => {
expect(canonicalQuestionAnswer(q, saved).selected).toEqual(["One per session"]);
// The key is the prompt's, unchanged.
expect(index[0].question.key).toBe(questionKey("single", q.prompt));
// A current label, or one naming no choice, is left alone.
const current = { ...saved, selected: ["One per person"] };
expect(canonicalQuestionAnswer(q, current)).toBe(current);
expect(canonicalQuestionAnswer(q, { ...saved, selected: ["Gone"] }).selected).toEqual(["Gone"]);
});

test("the export prints the current label, marked as the recommendation", () => {
const out = formatQuestionAnswersSection(questionExportItems(index), [saved]);
expect(out).toContain("Answer: One per session (your recommendation)");
expect(out).not.toContain("Each agent shows");
});

// #1702 review: a stored label more than one choice could claim stays as
// stored, never quietly becomes the first of them.
test("an ambiguous stored label stays as stored; an exact match beats a normalized one", () => {
const sharedFirstLine = parseQuestionBlock(
"question",
`Pick\n\n- Keep the cache\n for reads\n- Keep the cache\n for writes`,
)!;
expect(sharedFirstLine.choices.map((c) => c.label)).toEqual(["Keep the cache for reads", "Keep the cache for writes"]);
const stored = (label: string): QuestionAnswer => ({ v: 1, key: "q-00000001", kind: "single", prompt: "Pick", selected: [label] });
expect(canonicalQuestionAnswer(sharedFirstLine, stored("Keep the cache")).selected).toEqual(["Keep the cache"]);

const lookalikes = parseQuestionBlock("question", `Pick\n\n- **Alpha:** more\n- alpha\n for reads\n- Alpha — x`)!;
expect(lookalikes.choices.map((c) => c.label)).toEqual(["**Alpha:** more", "alpha for reads", "Alpha"]);
// "alpha" is exactly the second bullet's first line, its 0.28.1 label.
expect(canonicalQuestionAnswer(lookalikes, stored("alpha")).selected).toEqual(["alpha for reads"]);
// "ALPHA" matches several choices only after normalization: ambiguous.
expect(canonicalQuestionAnswer(lookalikes, stored("ALPHA")).selected).toEqual(["ALPHA"]);
// A current label is never remapped.
expect(canonicalQuestionAnswer(lookalikes, stored("Alpha")).selected).toEqual(["Alpha"]);
});

test("the lettered rule: plain bullets only, case-sensitive, per part on a multi question", () => {
const plain = (rec: string, kind = "question-multi") =>
parseQuestionBlock(kind, `Pick\n\n- a. Local, kept on the device\n- b. Server, kept per user\n- c. Nowhere at all\n\nRecommended: ${rec}`)!
.choices.map((c) => c.recommended);
expect(plain("a. Local, b. Server")).toEqual([true, true, false]);
expect(plain("a. Local and b. Server")).toEqual([true, true, false]);
expect(plain("a. Local; c. Nowhere")).toEqual([true, false, true]);
expect(plain("b. Default off; launch can allow it", "question")).toEqual([false, true, false]);
expect(plain("A. Smith's proposal is better", "question")).toEqual([false, false, false]);

// Task lists match exactly as on main (0.28.1): the letter alone names
// nothing, and a multi list is split as before.
const tasks = (rec: string, kind = "question-multi") =>
parseQuestionBlock(kind, `Pick\n\n- [ ] a. Local\n- [ ] b. Server\n- [ ] c. Nowhere\n\nRecommended: ${rec}`)!;
expect(tasks("a. Local, b. Server").choices.map((c) => c.recommended)).toEqual([true, true, false]);
expect(tasks("a. Local; c. Nowhere").choices.map((c) => c.recommended)).toEqual([true, false, true]);
const single = tasks("b. Default off", "question");
expect(single.choices.map((c) => c.recommended)).toEqual([false, false, false]);
expect(single.suggestedText).toBe("b. Default off");
expect(tasks("A. Local", "question").choices.map((c) => c.recommended)).toEqual([true, false, false]);
});

test("a recommendation naming a lettered option matches the option with that letter", () => {
const lettered = parseQuestionBlock(
"question",
`Merge?\n\n- **a. It stops at "ready".** It waits.\n- **b. "May merge when green", a checkbox.** Off by default.\n\n**Recommendation:** b. Default off; the launcher can allow it.`,
)!;
expect(lettered.choices.map((c) => c.recommended)).toEqual([false, true]);
// Two labels sharing the letter: no guess.
const twice = parseQuestionBlock("question", `Merge?\n\n- a. One\n- a) Two\n\nRecommended: a. whichever`)!;
expect(twice.choices.every((c) => !c.recommended)).toBe(true);
});
});

describe("question identity", () => {
test("the key ignores case, whitespace and emphasis but not the kind", () => {
expect(questionKey("single", "Where is **it**?")).toBe(questionKey("single", "where is it?"));
Expand Down
114 changes: 100 additions & 14 deletions packages/core/question-block.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,11 @@ export interface QuestionChoice {
/** Label as written (inline markdown). The export and answers quote it. */
label: string;
description?: string;
/** Other names this choice had or may be quoted by (plain bullets only):
* its full text, its first line, and that line's label as 0.28.1 and
* earlier read it. A saved answer quoting one of them selects this
* choice (see `canonicalQuestionAnswer`). Absent when there are none. */
aliases?: string[];
/** `- [x]`: the agent marked this choice as already decided. */
settled: boolean;
/** Named by the block's `Recommended:` line. */
Expand Down Expand Up @@ -329,6 +334,7 @@ const matchRecommendation = (
choices: QuestionChoice[],
multi: boolean,
names: string[][] = [],
plainBullets = false,
): number[] => {
const match = (candidate: string): number => {
const target = normalizeQuestionText(candidate);
Expand All @@ -350,17 +356,34 @@ const matchRecommendation = (
const hit = lead ? match(lead) : -1;
if (hit !== -1) return [hit];
}
if (!multi) return [];
for (const sep of [/\s*;\s*/, /\s*,\s*|\s+(?:and|&|\+)\s+/i]) {
const parts = text.split(sep).map((p) => p.trim()).filter(Boolean);
if (parts.length < 2) continue;
const hits = parts.map((p) => {
const hit = match(p);
return hit !== -1 ? hit : match(splitLabel(p).label);
// Plain bullets only (task lists match exactly as they always have):
// `b. Default off; …` names the one choice whose label starts `b.` / `b)`,
// same case, so `A. Smith's proposal` never names an `a.` choice.
const letteredHit = (candidate: string): number => {
if (!plainBullets) return -1;
const token = candidate.replace(/^[*_]+/, '').match(/^([A-Za-z]|\d{1,2})[.)]\s/)?.[1];
if (!token) return -1;
const hits = choices.flatMap((c, i) => {
const label = c.label.replace(/^[*_]+/, '');
return label.startsWith(`${token}.`) || label.startsWith(`${token})`) ? [i] : [];
});
if (hits.every((h) => h !== -1)) return [...new Set(hits)];
return hits.length === 1 ? hits[0] : -1;
};
if (multi) {
for (const sep of [/\s*;\s*/, /\s*,\s*|\s+(?:and|&|\+)\s+/i]) {
const parts = text.split(sep).map((p) => p.trim()).filter(Boolean);
if (parts.length < 2) continue;
const hits = parts.map((p) => {
const hit = match(p);
if (hit !== -1) return hit;
const head = match(splitLabel(p).label);
return head !== -1 ? head : letteredHit(p);
});
if (hits.every((h) => h !== -1)) return [...new Set(hits)];
}
}
return [];
const lettered = letteredHit(text);
return lettered !== -1 ? [lettered] : [];
};

/**
Expand Down Expand Up @@ -522,13 +545,22 @@ export const parseQuestionBlock = (directiveKind: string | undefined, body: stri
if (!prompt) return null;

// A pick question written with plain bullets: the bullets are the choices.
if (choices.length === 0 && directiveKind !== 'question-text' && plainBullets.length > 0) {
const choicesArePlainBullets = choices.length === 0 && directiveKind !== 'question-text' && plainBullets.length > 0;
if (choicesArePlainBullets) {
const bullets = plainBullets.slice(0, MAX_QUESTION_CHOICES);
const { splits, names } = plainBulletSplits(bullets);
bullets.forEach((bullet, i) => {
const { label, description } = splits[i];
if (!label) return;
choices.push({ label, ...(description ? { description } : {}), settled: false, recommended: false });
const aliases = [...new Set([bullet.text, ...names[i]])]
.filter((name) => name && normalizeQuestionText(name) !== normalizeQuestionText(label));
choices.push({
label,
...(description ? { description } : {}),
...(aliases.length > 0 ? { aliases } : {}),
settled: false,
recommended: false,
});
raws.push(bullet.text);
choiceNames.push(names[i]);
for (const index of bullet.contextIndices) dropContext.add(index);
Expand All @@ -546,9 +578,9 @@ export const parseQuestionBlock = (directiveKind: string | undefined, body: stri
const wrapped = recommendationWrapped ?? recommendation;
let hits: number[] = [];
if (kind !== 'text') {
hits = matchRecommendation(recommendation, raws, choices, kind === 'multi', choiceNames);
hits = matchRecommendation(recommendation, raws, choices, kind === 'multi', choiceNames, choicesArePlainBullets);
if (hits.length === 0 && wrapped !== recommendation) {
hits = matchRecommendation(wrapped, raws, choices, kind === 'multi', choiceNames);
hits = matchRecommendation(wrapped, raws, choices, kind === 'multi', choiceNames, choicesArePlainBullets);
}
}
if (hits.length > 0) for (const hit of hits) choices[hit].recommended = true;
Expand Down Expand Up @@ -792,6 +824,49 @@ export const parseQuestionAnswer = (value: unknown): QuestionAnswer | null => {
};
};

/**
* The answer with each picked label read against the question's current
* choices: a label that names a choice by one of its `aliases` (a label an
* older version gave it) becomes that choice's label, so an answer saved
* before the label changed still shows its pick. An exact name is tried
* before a normalized one (case, emphasis, punctuation), and a label that
* names no choice, or several, is kept as it is. Returns the same object
* when nothing maps.
*/
export const canonicalQuestionAnswer = <A extends QuestionAnswer>(
question: Pick<ParsedQuestion, 'choices'>,
answer: A,
): A => {
if (answer.selected.length === 0) return answer;
if (!question.choices.some((c) => c.aliases?.length)) return answer;
// Answers are capped on validation, so a long alias is matched capped too.
const names = question.choices.map((c) =>
(c.aliases ?? []).flatMap((alias) => [alias, cap(alias.trim(), MAX_QUESTION_CHOICE_LABEL_CHARS)]));
const labels = new Set(question.choices.map((c) => c.label));
// The one choice a stored label names, or -1 when none or several do: an
// ambiguous label (two bullets that shared a first line, or names that only
// differ in case or emphasis) stays as stored rather than picking one.
const only = (hits: number[]): number => (hits.length === 1 ? hits[0] : -1);
const exactHit = (stored: string): number =>
only(question.choices.flatMap((_, i) => (names[i].includes(stored) ? [i] : [])));
const normalizedHit = (stored: string): number => {
const target = normalizeQuestionText(stored);
if (!target) return -1;
return only(question.choices.flatMap((c, i) =>
normalizeQuestionText(c.label) === target || names[i].some((n) => normalizeQuestionText(n) === target) ? [i] : []));
};
let changed = false;
const selected = answer.selected.map((stored) => {
if (labels.has(stored)) return stored;
let hit = exactHit(stored);
if (hit === -1) hit = normalizedHit(stored);
if (hit === -1) return stored;
changed = true;
return question.choices[hit].label;
});
return changed ? { ...answer, selected: [...new Set(selected)] } : answer;
};

/** A choice was picked, "Other…" was filled, or free text was written. */
export const isQuestionAnswered = (answer: QuestionAnswer): boolean =>
answer.selected.length > 0 || !!answer.other?.trim() || !!answer.text?.trim();
Expand Down Expand Up @@ -935,6 +1010,10 @@ export interface QuestionExportItem {
settled: boolean;
/** The `[x]` choice labels. Absent reads as none. */
settledLabels?: string[];
/** The question's choices, so an answer that quotes an older label is
* printed with the current one (`canonicalQuestionAnswer`). Absent: the
* answer's labels are printed as stored. */
choices?: Pick<QuestionChoice, 'label' | 'aliases'>[];
}

export const questionExportItems = (indexed: ReadonlyArray<IndexedQuestion>): QuestionExportItem[] =>
Expand All @@ -947,6 +1026,7 @@ export const questionExportItems = (indexed: ReadonlyArray<IndexedQuestion>): Qu
...(question.suggestedText ? { suggestedText: question.suggestedText } : {}),
settled: question.choices.some((c) => c.settled),
settledLabels: question.choices.filter((c) => c.settled).map((c) => c.label),
...(question.choices.some((c) => c.aliases) ? { choices: question.choices.map(({ label, aliases }) => ({ label, ...(aliases ? { aliases } : {}) })) } : {}),
}));

export const QUESTION_ANSWERS_HEADING = 'Answers to your questions';
Expand All @@ -967,7 +1047,13 @@ export const formatQuestionAnswersSection = (
answers: ReadonlyArray<QuestionAnswer>,
opts: { headingLevel?: 2 | 3 } = {},
): string => {
const reported = answers.filter((a) => !isQuestionAnswerEmpty(a));
const choicesByKey = new Map(questions.map((q) => [q.key, q.choices]));
const reported = answers
.filter((a) => !isQuestionAnswerEmpty(a))
.map((a) => {
const choices = choicesByKey.get(a.key);
return choices ? canonicalQuestionAnswer({ choices: choices as QuestionChoice[] }, a) : a;
});
if (reported.length === 0) return '';
const h = '#'.repeat(opts.headingLevel ?? 2);
const sub = `${h}#`;
Expand Down
18 changes: 18 additions & 0 deletions packages/editor/webmcp/documentTools.questions.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import {
buildDocumentHooks,
buildDocumentTools,
createDocumentToolState,
questionViews,
type DocumentSessionView,
type DocumentToolAdapter,
} from './documentTools';
Expand Down Expand Up @@ -187,3 +188,20 @@ describe('answers are read-only to agents', () => {
expect(fx.annotations.find((a) => a.id === ann.id)?.questionAnswer?.selected).toEqual(['Local only']);
});
});

// 0.28.2: an answer saved under a 0.28.1 label (a wrapped plain bullet's
// first line) reads as the choice it picked, under the current label.
describe('read_document maps an answer saved under an older label', () => {
test('selected carries the current label', () => {
const markdown = ':::question\nHow should it be named?\n\n- **One per session:** each agent shows\n as its own machine.\n- **One per person:** shared.\n:::\n';
const blocks = parseMarkdownToBlocks(markdown);
const [q] = indexQuestionBlocks(blocks);
const ann = questionAnswerToAnnotation(q.blockId, {
v: 1, key: q.question.key, kind: 'single', prompt: q.question.prompt,
selected: ['**One per session:** each agent shows'],
});
const [view] = questionViews(blocks, [ann], []);
expect(view.answer?.selected).toEqual(['One per session']);
expect(view.status).toBe('answered');
});
});
9 changes: 7 additions & 2 deletions packages/editor/webmcp/documentTools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import { AnnotationType, type Annotation, type Block } from '@plannotator/ui/typ
import { generateId } from '@plannotator/ui/utils/generateId';
import { collectQuestionAnswers } from '@plannotator/ui/utils/questionAnswers';
import {
canonicalQuestionAnswer,
indexQuestionBlocks,
questionAnswerAnnotationId,
questionStatus,
Expand Down Expand Up @@ -313,9 +314,13 @@ export function questionViews(blocks: readonly Block[], annotations: readonly An
const indexed = indexQuestionBlocks(blocks);
const answers = collectQuestionAnswers(annotations);
const seen = new Set<string>();
const questionsByKey = new Map(indexed.map(({ question }) => [question.key, question]));
const answerView = (key: string): QuestionView['answer'] | undefined => {
const a = answers.get(key);
if (!a) return undefined;
const stored = answers.get(key);
if (!stored) return undefined;
// An answer quoting an older label of a choice reads as that choice.
const question = questionsByKey.get(key);
const a = question ? canonicalQuestionAnswer(question, stored) : stored;
return {
annotationId: questionAnswerAnnotationId(key),
selected: [...a.selected],
Expand Down
Loading
Loading