@shivaedev/work-board 0.8.0 → 0.9.1

package/src/responses/template.ts

@@ -0,0 +1,72 @@
+import type { RootContent } from "mdast";
+import type { ContainerDirective } from "mdast-util-directive";
+import remarkDirective from "remark-directive";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import { metadataParse } from "#metadata/parse.ts";
+import { templateLinks } from "./templateLinks.ts";
+import { isContainer, promptFrom, sliceNode } from "./templateNodes.ts";
+
+export interface Template {
+	readonly context: string;
+	readonly prompts: readonly Prompt[];
+}
+function nestedControl(node: RootContent): boolean {
+	return (
+		((node.type === "leafDirective" || node.type === "textDirective" || node.type === "containerDirective")
+			&& ["question", "option"].includes(node.name))
+		|| ("children" in node && node.children.some(nestedControl))
+	);
+}
+function scopedPrompt(
+	node: ContainerDirective,
+	source: string,
+	requests: readonly { readonly id: string; readonly state: string }[],
+	request: string,
+) {
+	const result = promptFrom(node, source);
+	if (result.request !== undefined && !requests.some((entry) => entry.id === result.request)) {
+		throw new Error("A question's request= must name an attention request in this document.");
+	}
+	if (result.request === undefined && requests.filter((entry) => entry.state === "open").length > 1) {
+		throw new Error("Use request= on question directives when a document has several open attention requests.");
+	}
+	return result.request === undefined || result.request === request ? result.prompt : undefined;
+}
+export function questionTemplate(context: string, request: string, file?: string): Template {
+	const parsed = metadataParse(context);
+	const parser = unified().use(remarkParse).use(remarkDirective);
+	const body = parsed.body.replace(/\r\n?/gu, "\n");
+	const original = parser.parse(body);
+	const source = file === undefined ? body : templateLinks(body, original.children, file);
+	const tree = parser.parse(source);
+	const definitions = tree.children
+		.filter((node) => node.type === "definition")
+		.map((node) => sliceNode(source, node))
+		.join("\n\n");
+	const prompts: Prompt[] = [];
+	const plain: string[] = [];
+
+	for (const node of tree.children) {
+		if (isContainer(node) && node.name === "question") {
+			const prompt = scopedPrompt(node, source, parsed.fields.attention ?? [], request);
+			if (prompt) {
+				prompts.push({
+					...prompt,
+					options: prompt.options.map((option) => ({ ...option, source: `${option.source}\n\n${definitions}`.trim() })),
+					source: `${prompt.source}\n\n${definitions}`.trim(),
+				});
+			}
+		} else {
+			if (nestedControl(node)) {
+				throw new Error("Use top-level question containers with direct option children.");
+			}
+			plain.push(sliceNode(source, node));
+		}
+	}
+	if (prompts.length > 32 || new Set(prompts.map((prompt) => prompt.id)).size !== prompts.length) {
+		throw new Error("Use at most 32 questions with unique IDs per attention request.");
+	}
+	return { context: plain.join("\n\n"), prompts };
+}

package/src/responses/templateHtml.ts

@@ -0,0 +1,26 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#page/escape.ts";
+import { renderMarkdown } from "#render/markdown.ts";
+import { questionTemplate } from "./template.ts";
+
+export const templateHtml = Effect.fn("WorkBoard.templateHtml")(function* (context: string, request: string, file: string) {
+	const template = questionTemplate(context, request, file);
+	function render(source: string) {
+		return renderMarkdown(source, { file, safe: true });
+	}
+	const background = yield* render(template.context);
+	const controls = yield* Effect.forEach(template.prompts, (prompt, index) =>
+		Effect.gen(function* () {
+			const description = yield* render(prompt.source);
+			const options = yield* Effect.forEach(prompt.options, (option, choice) =>
+				Effect.map(
+					render(option.source),
+					(html) =>
+						`<div class="question-option"><input id="question-${index}-${choice}" type="${prompt.mode === "one" ? "radio" : "checkbox"}" name="choice-${escapeHtml(prompt.id)}" value="${escapeHtml(option.id)}" data-option-source="${escapeHtml(option.source)}"><div><label for="question-${index}-${choice}">Option ${escapeHtml(option.id)}</label>${html}</div></div>`,
+				),
+			);
+			return `<fieldset data-prompt="${escapeHtml(prompt.id)}" data-mode="${prompt.mode}" data-source="${escapeHtml(prompt.source)}"><legend>Question ${index + 1} · ${escapeHtml(prompt.id)}</legend>${description}<p>${prompt.mode === "text" ? "Answer in your own words" : `${prompt.mode === "one" ? "Choose one option" : "Choose any combination"}, or answer in your own words`}. Nothing is selected for you.</p>${options.join("")}${prompt.mode === "text" ? "" : '<button type="button" data-clear-choices>Clear selections</button>'}<label>Additional text / another answer<textarea data-answer-text maxlength="8192" rows="3"></textarea></label></fieldset>`;
+		}),
+	);
+	return { background, controls: controls.join(""), hasPrompts: template.prompts.length > 0 };
+});

package/src/responses/templateLinks.ts

@@ -0,0 +1,43 @@
+import type { RootContent } from "mdast";
+import { fileUrl } from "#files/url.ts";
+
+function destination(url: string, file: string) {
+	if (url.startsWith("//") || url.search(/^[a-z][a-z\d+.-]*:/iu) === 0) {
+		return url;
+	}
+	const resolved = new URL(url, `http://work-board.local${fileUrl(file)}`);
+	return resolved.pathname + resolved.search + resolved.hash;
+}
+function titleSuffix(title: string | null | undefined) {
+	return title ? ` "${title.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"` : "";
+}
+export function templateLinks(source: string, nodes: readonly RootContent[], file: string) {
+	const edits: { readonly start: number; readonly end: number; readonly text: string }[] = [];
+	function visit(node: RootContent) {
+		const start = node.position?.start.offset;
+		const end = node.position?.end.offset;
+		if (start === undefined || end === undefined) {
+			return;
+		}
+		if (node.type === "link") {
+			const label = source.slice(node.children.at(0)?.position?.start.offset, node.children.at(-1)?.position?.end.offset);
+			edits.push({ end, start, text: `[${label}](<${destination(node.url, file)}>${titleSuffix(node.title)})` });
+		} else if (node.type === "image") {
+			edits.push({
+				end,
+				start,
+				text: `![${(node.alt ?? "").replaceAll("[", "\\[").replaceAll("]", "\\]")}](<${destination(node.url, file)}>${titleSuffix(node.title)})`,
+			});
+		} else if (node.type === "definition") {
+			edits.push({ end, start, text: `[${node.label ?? node.identifier}]: <${destination(node.url, file)}>${titleSuffix(node.title)}` });
+		} else if ("children" in node) {
+			node.children.forEach(visit);
+		}
+	}
+	nodes.forEach(visit);
+	let result = source;
+	for (const edit of edits.sort((a, b) => b.start - a.start)) {
+		result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+	}
+	return result;
+}

package/src/responses/templateNodes.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import type { RootContent } from "mdast";
+import type { ContainerDirective } from "mdast-util-directive";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import { Identity } from "#path/Identity.ts";
+
+const Id = Identity.check(Schema.isMaxLength(128));
+const PromptFields = Schema.Struct({ id: Id, request: Schema.optional(Identity), select: Schema.optional(Schema.Literals(["one", "many", "text"])) });
+const OptionFields = Schema.Struct({ id: Id });
+
+export function sliceNode(source: string, node: RootContent) {
+	return source.slice(node.position?.start.offset, node.position?.end.offset);
+}
+export function isContainer(node: RootContent): node is ContainerDirective {
+	return node.type === "containerDirective";
+}
+function hasControl(node: RootContent): boolean {
+	return (
+		((node.type === "containerDirective" || node.type === "leafDirective" || node.type === "textDirective")
+			&& ["question", "option"].includes(node.name))
+		|| ("children" in node && node.children.some(hasControl))
+	);
+}
+export function promptFrom(node: ContainerDirective, source: string) {
+	const attrs = Schema.decodeUnknownSync(PromptFields, { onExcessProperty: "error" })(node.attributes ?? {});
+	const options = node.children.filter((child) => isContainer(child) && child.name === "option");
+	const description = node.children.filter((child) => !(isContainer(child) && child.name === "option"));
+	if (
+		description.some(hasControl)
+		|| description.length === 0
+		|| options.length > 32
+		|| (attrs.select === "text" ? options.length > 0 : options.length === 0)
+	) {
+		throw new Error("A question needs Markdown context and 1–32 direct options (or select=text without options), without nested questions.");
+	}
+	const choices = options.map((option) => {
+		if (!isContainer(option) || option.children.some(hasControl) || option.children.length === 0) {
+			throw new Error("Options need Markdown descriptions and cannot nest response controls.");
+		}
+		const fields = Schema.decodeUnknownSync(OptionFields, { onExcessProperty: "error" })(option.attributes ?? {});
+		return { id: fields.id, source: option.children.map((child) => sliceNode(source, child)).join("\n\n") };
+	});
+	if (new Set(choices.map((option) => option.id)).size !== choices.length) {
+		throw new Error("Option IDs must be unique within each question.");
+	}
+	return {
+		prompt: {
+			id: attrs.id,
+			mode: attrs.select ?? "one",
+			options: choices,
+			source: description.map((child) => sliceNode(source, child)).join("\n\n"),
+		} satisfies Prompt,
+		request: attrs.request,
+	};
+}

package/src/responses/validateSupersedes.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { type DraftInput, type Question, ResponseFailed } from "#browser/responses/schema.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { questionFrom, responseFrom } from "./records.ts";
+
+export function validateSupersedes(input: DraftInput, question: Question, data: Snapshot) {
+	if (input.supersedes === undefined) {
+		return Effect.void;
+	}
+	const matches = data.model.ids.get(input.supersedes);
+	const previous = matches?.length === 1 && matches[0] ? responseFrom(matches[0]) : undefined;
+	const context = previous && data.model.ids.get(previous.response.question);
+	const old = context?.length === 1 && context[0] ? questionFrom(context[0]) : undefined;
+	return old
+		&& previous
+		&& previous.response.reviewedRevision === old.question.reviewedRevision
+		&& old.question.item === question.question.item
+		&& old.question.request === question.question.request
+		&& input.supersedes !== input.id
+		? Effect.void
+		: Effect.fail(
+				new ResponseFailed({ code: "Conflict", message: "Supersedes must identify one recorded response to this item's attention request." }),
+			);
+}

package/src/responses/validatedInput.ts

@@ -0,0 +1,45 @@
+import { answerBody } from "#browser/responses/answerBody.ts";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import type { DraftInput, PromptAnswer } from "#browser/responses/schema.ts";
+import { questionTemplate } from "./template.ts";
+
+function answerFor(prompt: Prompt, answer: PromptAnswer | undefined, required: boolean) {
+	if (!answer || answer.prompt !== prompt.id) {
+		throw new Error("Submit one answer per question, in template order.");
+	}
+	if (new Set(answer.selected).size !== answer.selected.length || (prompt.mode === "one" && answer.selected.length > 1)) {
+		throw new Error("The selected options do not match the question's selection mode.");
+	}
+	if (answer.selected.some((id) => !prompt.options.some((option) => option.id === id))) {
+		throw new Error("A selected option is not in the reviewed template.");
+	}
+	if (required && answer.selected.length === 0 && !answer.text.trim()) {
+		throw new Error("Answer every question with a selection or additional text, or use Clarify / Not now.");
+	}
+}
+export function validatedInput(input: DraftInput, context: string, request: string, file?: string): DraftInput {
+	const template = questionTemplate(context, request, file);
+	if (input.answers === undefined) {
+		if (template.prompts.length > 0 && input.type === "answer") {
+			throw new Error("This question packet requires answers for all prompts.");
+		}
+		if (!input.body.trim()) {
+			throw new Error("A response needs text or answers to the question packet.");
+		}
+		return input;
+	}
+	if (input.answers.length !== template.prompts.length || template.prompts.length === 0) {
+		throw new Error("The answer packet does not match the reviewed questions.");
+	}
+	template.prompts.forEach((prompt, index) => {
+		answerFor(prompt, input.answers?.[index], input.type === "answer");
+	});
+	if (input.type !== "answer" && !input.body.trim() && !input.answers.some((answer) => answer.text.trim())) {
+		throw new Error("Clarify / Not now needs explanatory text.");
+	}
+	const body = answerBody(template.prompts, input.answers, input.body);
+	if (body.length > 32_768) {
+		throw new Error("The complete recorded response exceeds 32768 characters. Shorten the response or split the source request.");
+	}
+	return { ...input, body };
+}

package/src/serve-cli.ts

@@ -4,7 +4,7 @@ import { Effect, Layer, Option, Path } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { HOST, serveBoard } from "./serve.ts";
 
-const VERSION = "0.8.0";
+const VERSION = "0.9.1";
 
 const serve = Effect.fn("WorkBoard.serve")(function* (input: {
 	readonly dir: string;