@lernapps/app-templates 0.0.1 → 0.1.1

package/runtime/explainer/generated/texts.ts

@@ -0,0 +1,257 @@
+// The texts of a task: its template filled in with the values (the placeholders ⟦name⟧ the build leaves), the numbers
+// as a locale writes them, the checks of the placeholders, the steps and the hint.
+import { evaluate, ExpressionError, Localized, parse, type Value, variables } from "../expression.ts";
+import { Fraction } from "../fraction.ts";
+import { inLanguage, localeOf, type Text } from "../../shared/languages.ts";
+import { escape } from "../../shared/html.ts";
+import { type Generated, type LanguageTemplates, type Task, type Templates } from "./types.ts";
+import { kindOf } from "./comparator.ts";
+
+const PATH = String.raw`[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*`;
+/** A placeholder: two braces around a name or a name's field, nothing else inside. */
+const PLACEHOLDER = new RegExp(String.raw`\{\{(${PATH})\}\}`, "g");
+/** What looks meant as a placeholder but is not one: one brace in prose, or spaces inside two braces. */
+const ONE_BRACE = new RegExp(String.raw`(?<!\{)\{(${PATH})\}(?!\})`, "g");
+/** Anything between two braces, as written: a placeholder, or what only looks like one ({{opts[0].x}}, {{}}, {{1x}}). */
+const BRACED = /\{\{([^{}]*)\}\}/g;
+const PATH_ONLY = new RegExp(String.raw`^${PATH}$`);
+const SPACED = new RegExp(String.raw`\{\{\s*(${PATH})\s*\}\}`, "g");
+/** A formula ($…$) or a run of prose, in a template. */
+const SEGMENT = /\$((?:\\.|[^\\$\n])+?)\$|([^$]+)/g;
+
+const formats = new Map<string, Intl.NumberFormat>();
+/** A number as the page shows it: up to six decimals, no grouping (a learner would type 1500, not 1.500). */
+export function formatNumber(value: Fraction, lang: string, decimals?: number): string {
+  const key = `${lang}:${decimals ?? ""}`;
+  let format = formats.get(key);
+  if (format === undefined) {
+    format = new Intl.NumberFormat(localeOf(lang), {
+      maximumFractionDigits: decimals ?? 6,
+      ...(decimals === undefined ? {} : { minimumFractionDigits: decimals }),
+      useGrouping: false,
+    });
+    formats.set(key, format);
+  }
+  return format.format(value.toNumber());
+}
+
+/** A value as the learner reads it, in `lang`. */
+export function label(value: Value, lang: string): string {
+  if (value instanceof Fraction) return formatNumber(value, lang);
+  if (value instanceof Localized) return value.in(lang);
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return (value as readonly Value[]).map((item) => label(item, lang)).join(", ");
+  throw new ExpressionError("a record cannot be shown; name one of its fields, e.g. {{e.name}}");
+}
+
+/** The answer as the learner reads it: a sum of money with two decimals when it has any. */
+export function answerLabel(spec: Generated, task: Task, lang: string): string {
+  const kind = kindOf(spec.answer.compare);
+  if (kind.kind === "number" && task.answer instanceof Fraction) {
+    return formatNumber(task.answer, lang, kind.money && !task.answer.isInteger() ? 2 : undefined);
+  }
+  return label(task.answer, lang);
+}
+
+/** A template's placeholders as tokens: {{G}} becomes ⟦G⟧, inside a formula ($…$) {\text{⟦G⟧}}. */
+export function tokenize(text: string): string {
+  return text.replace(SEGMENT, (whole, math: string | undefined, prose: string | undefined) =>
+    math !== undefined
+      ? `$${math.replace(PLACEHOLDER, (_placeholder, path: string) => `{\\text{⟦${path}⟧}}`)}$`
+      : (prose ?? whole).replace(PLACEHOLDER, (_placeholder, path: string) => `⟦${path}⟧`),
+  );
+}
+
+/** The placeholders of a template, by their path (G, e.name, answer). */
+export function placeholdersIn(text: string): string[] {
+  return [...text.matchAll(PLACEHOLDER)].map((match) => match[1] ?? "");
+}
+
+/**
+ * The problems of the placeholders of one template: unknown roots, one brace in prose, spaces inside, and double
+ * braces around anything but a name or a name's field (an index, a number, nothing). A literal {{ in a formula is
+ * written { { }.
+ */
+export function placeholderProblems(text: string, known: ReadonlySet<string>): string[] {
+  const problems: string[] = [];
+  const list = [...known].map((name) => `{{${name}}}`).join(", ");
+  for (const path of placeholdersIn(text)) {
+    const root = path.split(".")[0] ?? "";
+    if (!known.has(root)) {
+      problems.push(
+        `{{${path}}} is an unknown placeholder: ${root} is not declared in given; declare it, or use one of ${list}`,
+      );
+    }
+  }
+  for (const match of text.matchAll(SPACED)) {
+    if (match[0] !== `{{${match[1]}}}`) {
+      problems.push(`${match[0]} has spaces inside; a placeholder is written {{${match[1]}}}, without spaces`);
+    }
+  }
+  for (const match of text.matchAll(BRACED)) {
+    const inner = match[1] ?? "";
+    if (PATH_ONLY.test(inner) || PATH_ONLY.test(inner.trim())) continue; // a placeholder, or reported as spaced
+    problems.push(
+      `${match[0]} is no placeholder: a placeholder is a name or a name's field ({{e.brauch}}); to show one record, pick it on its own (given: { e: { pick: 1, from: { data: feste } } }) and write {{e.brauch}}; a literal {{ in a formula is written { {`,
+    );
+  }
+  for (const match of text.matchAll(SEGMENT)) {
+    if (match[2] === undefined) continue;
+    for (const one of match[2].matchAll(ONE_BRACE)) {
+      const root = (one[1] ?? "").split(".")[0] ?? "";
+      if (known.has(root)) {
+        problems.push(`{${one[1]}} has one pair of braces; a placeholder is written with two: {{${one[1]}}}`);
+      }
+    }
+  }
+  return problems;
+}
+
+/** One template of an exercise as written, in one language: where it is, and its text. */
+export interface Written {
+  /** The path in the exercise; for a text by language it ends with the language. */
+  path: (string | number)[];
+  lang?: string;
+  text: string;
+}
+
+/** The templates of an exercise as written: the task, the steps, the hint and the messages. */
+export function writtenTemplates(spec: Generated): Written[] {
+  const written: Written[] = [];
+  const add = (path: (string | number)[], text: Text | undefined) => {
+    if (text === undefined) return;
+    if (typeof text === "string") written.push({ path, text });
+    else for (const [lang, each] of Object.entries(text)) written.push({ path: [...path, lang], lang, text: each });
+  };
+  add(["task", "text"], spec.task.text);
+  (spec.steps ?? []).forEach((step, index) => add(["steps", index], step));
+  add(["hint"], spec.hint);
+  (spec.mistakes ?? []).forEach((mistake, index) => add(["mistakes", index, "message"], mistake.message));
+  return written;
+}
+
+/** The problems of the placeholders of an exercise's templates, each at its path. */
+export function templateProblems(spec: Generated): { path: (string | number)[]; lang?: string; message: string }[] {
+  const declared = [...Object.keys(spec.given), "answer"];
+  return writtenTemplates(spec).flatMap(({ path, lang, text }) => {
+    const known = new Set(declared);
+    return placeholderProblems(text, known).map((message) => ({
+      path,
+      ...(lang === undefined ? {} : { lang }),
+      message,
+    }));
+  });
+}
+
+/**
+ * The variables of `given` that the exercise never uses: in no placeholder of its templates, and in none of the
+ * expressions of the answer (with the options of a choice) and the mistakes. `where` does not
+ * count: a value drawn only to be filtered is never seen.
+ */
+export function unusedVariables(spec: Generated): string[] {
+  const used = new Set<string>();
+  for (const { text } of writtenTemplates(spec))
+    for (const path of placeholdersIn(text)) used.add(path.split(".")[0] ?? "");
+  const expressions = [spec.answer.value, ...(spec.mistakes ?? []).map((mistake) => mistake.value)];
+  const compare = spec.answer.compare;
+  if (typeof compare === "object") {
+    const options = (compare as Record<string, unknown>)["choice"];
+    if (typeof options === "string") expressions.push(options);
+  }
+  for (const source of expressions) {
+    try {
+      variables(parse(source), used);
+    } catch {
+      // an expression that does not parse is reported on its own
+    }
+  }
+  return Object.keys(spec.given).filter((name) => !used.has(name));
+}
+
+/** The value of a placeholder's path in a task, or undefined when it has none. */
+export function placeholderValue(
+  spec: Generated,
+  task: Task,
+  path: string,
+  lang: string,
+): { text: string; number?: Fraction } | undefined {
+  if (path === "answer") {
+    return { text: answerLabel(spec, task, lang), ...(task.answer instanceof Fraction ? { number: task.answer } : {}) };
+  }
+  try {
+    const value = evaluate(parse(path), task.values);
+    return { text: label(value, lang), ...(value instanceof Fraction ? { number: value } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A template with the values of a task: HTML (escaped, numbers in formulas as <mn>) or plain text. */
+export function fill(
+  template: string,
+  spec: Generated,
+  task: Task,
+  lang: string,
+  mode: "html" | "text" = "html",
+): string {
+  const withMath =
+    mode === "html"
+      ? template.replace(/<mtext>⟦([^⟧]+)⟧<\/mtext>/g, (_whole, path: string) => {
+          const value = placeholderValue(spec, task, path, lang);
+          if (value === undefined) return `<mtext>{{${escape(path)}}}</mtext>`;
+          if (value.number === undefined) return `<mtext>${escape(value.text)}</mtext>`;
+          const negative = value.number.compare(Fraction.of(0)) < 0;
+          const digits = escape(negative ? value.text.replace(/^[-−]/, "") : value.text);
+          return negative ? `<mo>−</mo><mn>${digits}</mn>` : `<mn>${digits}</mn>`;
+        })
+      : template;
+  return withMath.replace(/⟦([^⟧]+)⟧/g, (_whole, path: string) => {
+    const value = placeholderValue(spec, task, path, lang);
+    if (value === undefined) return `{{${path}}}`;
+    return mode === "html" ? escape(value.text) : value.text;
+  });
+}
+
+/**
+ * A template as its author wrote it (restricted Markdown, formulas as $…$) with each placeholder replaced by its value
+ * as the learner reads it, in `lang`.
+ */
+export function fillSource(text: Text, spec: Generated, task: Task, lang: string): string {
+  return inLanguage(text, lang).replace(
+    PLACEHOLDER,
+    (whole, path: string) => placeholderValue(spec, task, path, lang)?.text ?? whole,
+  );
+}
+
+export const templatesIn = (templates: Templates, lang: string): LanguageTemplates =>
+  templates[lang] ?? templates["de"] ?? { task: "", steps: [], messages: [] };
+
+/** The task's text as HTML, in `lang`. */
+export function taskText(spec: Generated, task: Task, lang: string, templates: Templates): string {
+  return fill(templatesIn(templates, lang).task, spec, task, lang);
+}
+
+/** The steps of the solution as HTML, in `lang`. */
+export function stepsOf(spec: Generated, task: Task, lang: string, templates: Templates): string[] {
+  return templatesIn(templates, lang).steps.map((step) => fill(step, spec, task, lang));
+}
+
+/** The hint as HTML, in `lang`, if the exercise has one. */
+export function hintOf(spec: Generated, task: Task, lang: string, templates: Templates): string | undefined {
+  const hint = templatesIn(templates, lang).hint;
+  return hint === undefined ? undefined : fill(hint, spec, task, lang);
+}
+
+/** The text of HTML, as a learner reads it: tags left out, entities resolved, white space folded. */
+export function plainText(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&")
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/runtime/explainer/generated/types.ts

@@ -0,0 +1,103 @@
+// Generated exercises (`generated`), the explainer's native notation for exercises drawn from a seed, in the style of
+// property-based testing: arbitraries (`given`), preconditions (`where`), a task template,
+// an answer with a comparator, typical mistakes with their messages, a hint and the steps, and examples: answers
+// the build runs through the check of every seed's task (exampleProblems), never shown to learners. The same code runs at build
+// time (the worked tasks without JavaScript, the property test over fixed seeds) and in the browser (a live task for
+// any seed, "Neue Aufgabe"), so both agree. The comparator maps the answer onto the answer kinds of a question: number,
+// choice, order, set and pairs become the number, single-choice, ordering, multiple-choice and matching
+// questions, so controls, checker and feedback come from the shared questions.
+//
+// Templates are rendered by the build (restricted Markdown, formulas as MathML) with each placeholder {{name}} as a
+// token ⟦name⟧ (inside a formula \text{⟦name⟧}); fill() puts in the values of a task, so the browser needs no Markdown
+// or formula renderer. No Node and no DOM here.
+//
+// A placeholder is always written with two braces and nothing else inside: {{G}}, {{e.name}}, {{answer}}, in prose
+// and in formulas alike. One brace is never a placeholder: in prose {G} is an error, in a formula it is a LaTeX group,
+// so a bare letter (G, {G}, \frac{W}{G}) is always the letter. The one LaTeX form this takes away, a double group
+// around a lone name ({{G}}), means the same as the letter alone, so nothing is lost; any other group ({{G}^2},
+// {{G} + 1}) stays a group. To fill in a value where the formula needs a group, keep the group: \frac{{{W}}}{{{G}}}.
+// Two braces with spaces inside ({{ G }}) are an error everywhere, as they were most likely meant as a placeholder.
+
+// This module: the types of a generated exercise, its task and its data.
+import { type Value } from "../expression.ts";
+import { type Text } from "../../shared/languages.ts";
+
+/** A literal of a list in the content: a number, a string, or a text by language. */
+export type Literal = number | string | Readonly<Record<string, string>>;
+/** A list of literals, or the records of a data file src/data/<name>.yaml. */
+export type Source = readonly Literal[] | { readonly data: string };
+
+/** One arbitrary of `given`: exactly one of int, decimal, oneOf, pick (with from). */
+export interface Arbitrary {
+  readonly int?: readonly [number, number];
+  readonly decimal?: readonly [number, number];
+  readonly step?: number;
+  readonly oneOf?: readonly Literal[];
+  readonly pick?: number;
+  readonly from?: Source;
+  readonly distinct?: boolean;
+}
+
+export interface NumberCompare {
+  readonly format?: "integer" | "decimal" | "money" | "percent";
+  readonly decimals?: number;
+  readonly tolerance?: number;
+  readonly unit?: Text;
+}
+
+export type Compare =
+  | "number"
+  | "order"
+  | "pairs"
+  | { readonly number: NumberCompare }
+  | { readonly choice: readonly Literal[] | string }
+  | { readonly pairs: { readonly left: string; readonly right: string } };
+
+export interface Generated {
+  readonly type: "generated";
+  readonly id: string;
+  readonly given: Readonly<Record<string, Arbitrary>>;
+  readonly where?: readonly string[];
+  readonly task: { readonly text: Text };
+  readonly answer: { readonly value: string; readonly compare: Compare };
+  readonly mistakes?: readonly { readonly value: string; readonly message: Text }[];
+  readonly hint?: Text;
+  readonly steps?: readonly Text[];
+  /** The sentence above the live task; the page's own when absent. */
+  readonly practice?: Text;
+  /**
+   * Test cases for the build, never shown to learners: answers as expressions of given and answer, which the check
+   * of every seed's task must accept or reject (exampleProblems).
+   */
+  readonly examples?: { readonly accepted?: readonly string[]; readonly rejected?: readonly string[] };
+}
+
+/**
+ * A value of a data record: a number, a truth value, a text (a string, or a map by language), or, for what a component
+ * shows, a list or a record of values.
+ */
+export type DataValue = number | boolean | Text | readonly DataValue[] | { readonly [field: string]: DataValue };
+/** A record of a data file: its fields by name. */
+export type DataRecord = Readonly<Record<string, DataValue>>;
+/** The records of the data files, by name. */
+export type Data = Readonly<Record<string, readonly DataRecord[]>>;
+
+/** The templates of an exercise in one language, rendered by the build, with tokens for the placeholders. */
+export interface LanguageTemplates {
+  /** The task, inline HTML (no paragraph). */
+  task: string;
+  steps: string[];
+  hint?: string | undefined;
+  /** The mistakes' messages, plain text. */
+  messages: string[];
+}
+export type Templates = Readonly<Record<string, LanguageTemplates>>;
+
+/** A task drawn from a seed: the values of `given`, the answer, the mistakes, the options of a choice or set. */
+export interface Task {
+  seed: number;
+  values: Record<string, Value>;
+  answer: Value;
+  mistakes: Value[];
+  options?: Value[];
+}

package/runtime/explainer/generated/values.ts

@@ -0,0 +1,136 @@
+// The values of a generated exercise: the arbitraries (`given`) drawn from a seed, the preconditions (`where`), the
+// compiled expressions, and the task of a seed.
+import { evaluate, type Expression, ExpressionError, Localized, parse, type Rec, type Value } from "../expression.ts";
+import { Fraction } from "../fraction.ts";
+import { hash, random, shuffled } from "../../shared/questions/question.ts";
+import {
+  type Arbitrary,
+  type Data,
+  type DataRecord,
+  type DataValue,
+  type Generated,
+  type Literal,
+  type Source,
+  type Task,
+} from "./types.ts";
+import { kindOf } from "./comparator.ts";
+
+/** How many draws a seed may take until `where` holds. */
+export const ATTEMPTS = 100;
+
+const literal = (value: Literal): Value =>
+  typeof value === "number" ? Fraction.from(value) : typeof value === "string" ? value : new Localized(value);
+
+/** A value of a data record: a map of strings is a text by language, any other map a record. */
+function dataValue(value: DataValue): Value {
+  if (typeof value === "number") return Fraction.from(value);
+  if (typeof value === "boolean" || typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map(dataValue);
+  const fields = Object.entries(value as Record<string, DataValue>);
+  return fields.every(([, field]) => typeof field === "string")
+    ? new Localized(value as Readonly<Record<string, string>>)
+    : record(value as DataRecord);
+}
+
+export function record(source: DataRecord): Rec {
+  return Object.fromEntries(Object.entries(source).map(([key, value]) => [key, dataValue(value)]));
+}
+
+export function items(source: Source, data: Data): Value[] {
+  if (Array.isArray(source)) return (source as readonly Literal[]).map(literal);
+  const name = (source as { data: string }).data;
+  const records = data[name];
+  if (records === undefined) throw new ExpressionError(`src/data/${name}.yaml does not exist`);
+  return records.map(record);
+}
+
+/** The value of one arbitrary, drawn with `next`. */
+export function draw(arbitrary: Arbitrary, next: () => number, data: Data): Value {
+  const range = arbitrary.int ?? arbitrary.decimal;
+  if (range !== undefined) {
+    const [min, max] = range;
+    const step = Fraction.from(arbitrary.step ?? 1);
+    const low = Fraction.from(min);
+    const count = Math.floor(Fraction.from(max).sub(low).div(step).toNumber() + 1e-9) + 1;
+    return low.add(step.mul(Fraction.of(Math.floor(next() * count))));
+  }
+  if (arbitrary.oneOf !== undefined) {
+    const list = arbitrary.oneOf;
+    return literal(list[Math.floor(next() * list.length)] as Literal);
+  }
+  const list = items(arbitrary.from ?? [], data);
+  const count = arbitrary.pick ?? 1;
+  const picked: Value[] = [];
+  if (arbitrary.distinct === true) {
+    const order = shuffled(list.length, Math.floor(next() * 2 ** 31));
+    for (const index of order.slice(0, count)) picked.push(list[index] as Value);
+  } else {
+    for (let i = 0; i < count; i++) picked.push(list[Math.floor(next() * list.length)] as Value);
+  }
+  return count === 1 && arbitrary.pick === 1 ? (picked[0] as Value) : picked;
+}
+
+/** The parsed expressions of an exercise, once per exercise. */
+interface Compiled {
+  where: Expression[];
+  answer: Expression;
+  mistakes: Expression[];
+  options?: Expression;
+}
+const compiledCache = new WeakMap<Generated, Compiled>();
+export function compiled(spec: Generated): Compiled {
+  let found = compiledCache.get(spec);
+  if (found === undefined) {
+    const kind = kindOf(spec.answer.compare);
+    found = {
+      where: (spec.where ?? []).map((source) => parse(source)),
+      answer: parse(spec.answer.value),
+      mistakes: (spec.mistakes ?? []).map((mistake) => parse(mistake.value)),
+      ...(kind.kind === "choice" && typeof kind.options === "string" ? { options: parse(kind.options) } : {}),
+    };
+    compiledCache.set(spec, found);
+  }
+  return found;
+}
+
+/** The values of `given` for a seed and an attempt. */
+export function values(spec: Generated, seed: number, attempt: number, data: Data): Record<string, Value> {
+  const next = random(hash(`${spec.id}#${seed}#${attempt}`));
+  const drawn: Record<string, Value> = {};
+  for (const [name, arbitrary] of Object.entries(spec.given)) drawn[name] = draw(arbitrary, next, data);
+  return drawn;
+}
+
+/** Whether every precondition holds for these values. */
+export function holds(spec: Generated, env: Record<string, Value>): boolean {
+  return compiled(spec).where.every((condition, index) => {
+    const value = evaluate(condition, env);
+    if (typeof value !== "boolean") {
+      throw new ExpressionError(`where[${index}] needs true or false, not a value`);
+    }
+    return value;
+  });
+}
+
+/** Thrown when no draw of a seed passes `where`. */
+export class StarvedError extends ExpressionError {}
+
+/** The task of `seed`: the first draw whose values pass `where`, with the answer, the mistakes and the options. */
+export function generate(spec: Generated, seed: number, data: Data): Task {
+  const code = compiled(spec);
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const env = values(spec, seed, attempt, data);
+    if (!holds(spec, env)) continue;
+    const answer = evaluate(code.answer, env);
+    const task: Task = { seed, values: env, answer, mistakes: code.mistakes.map((mistake) => evaluate(mistake, env)) };
+    const kind = kindOf(spec.answer.compare);
+    if (kind.kind === "choice") {
+      const options =
+        code.options === undefined ? (kind.options as readonly Literal[]).map(literal) : evaluate(code.options, env);
+      if (!Array.isArray(options)) throw new ExpressionError(`the options of choice are not a list`);
+      task.options = [...(options as Value[])];
+    }
+    return task;
+  }
+  throw new StarvedError(`where holds in none of ${ATTEMPTS} draws for seed ${seed}`);
+}