@longsightgroup/qti3-core 0.9.2 → 0.9.3

package/src/processing-evaluator-variable.ts

@@ -0,0 +1,81 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { mapOrMatchResponse, scoreAreaMapping } from "./processing-mapping.js";
+import { isNullResponse, qtiMatchValues } from "./processing-values.js";
+import {
+  defaultValueForIdentifier,
+  getResponseDeclaration,
+  resolveVariableValue,
+} from "./processing-variables.js";
+
+type VariableExpression = Extract<
+  QtiProcessingExpression,
+  {
+    type:
+      | "isNull"
+      | "matchCorrect"
+      | "mapResponse"
+      | "mapResponsePoint"
+      | "correct"
+      | "default"
+      | "variable";
+  }
+>;
+
+export function evaluateVariableExpression(
+  expression: VariableExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "isNull":
+      return isNullResponse(context.responses[expression.identifier] ?? null);
+    case "matchCorrect": {
+      const declaration = getResponseDeclaration(context.document, expression.correctIdentifier);
+      return declaration
+        ? qtiMatchValues(
+            context.responses[expression.identifier] ?? null,
+            context.correctResponses[expression.correctIdentifier] ?? null,
+            declaration.cardinality === "ordered",
+          )
+        : false;
+    }
+    case "mapResponse": {
+      const declaration = getResponseDeclaration(context.document, expression.identifier);
+      return declaration
+        ? mapOrMatchResponse(
+            declaration,
+            context.responses[expression.identifier] ?? null,
+            context.correctResponses[expression.identifier] ?? null,
+          )
+        : 0;
+    }
+    case "mapResponsePoint": {
+      const declaration = getResponseDeclaration(context.document, expression.identifier);
+      return declaration?.areaMapping
+        ? scoreAreaMapping(
+            context.responses[expression.identifier] ?? null,
+            declaration.areaMapping,
+          )
+        : 0;
+    }
+    case "correct":
+      return context.correctResponses[expression.identifier] ?? null;
+    case "default":
+      return defaultValueForIdentifier(context.document, expression.identifier);
+    case "variable":
+      return (
+        resolveVariableValue(
+          context.document,
+          expression.identifier,
+          context.responses,
+          context.outcomes,
+          context.templateValues,
+        ) ??
+        context.undeclaredResponseValue(expression.identifier) ??
+        null
+      );
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-evaluator.ts

@@ -0,0 +1,173 @@
+import type { QtiDocument, QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { QtiCustomOperatorRegistry } from "./custom-operators.js";
+import { evaluateBooleanExpression } from "./processing-evaluator-boolean.js";
+import {
+  evaluateCollectionExpression,
+  evaluateRepeatExpression,
+} from "./processing-evaluator-collection.js";
+import { evaluateComparisonExpression } from "./processing-evaluator-comparison.js";
+import { evaluateCustomOperatorExpression } from "./processing-evaluator-custom.js";
+import { evaluateGeometryExpression } from "./processing-evaluator-geometry.js";
+import { evaluateNumericExpression } from "./processing-evaluator-numeric.js";
+import { evaluateStringExpression } from "./processing-evaluator-string.js";
+import { evaluateVariableExpression } from "./processing-evaluator-variable.js";
+import { isRecordValue, numericValueOrNull } from "./processing-values.js";
+
+export interface EvaluationContext {
+  document: QtiDocument;
+  responses: Record<string, QtiValue>;
+  outcomes: Record<string, QtiValue>;
+  templateValues: Record<string, QtiValue>;
+  correctResponses: Record<string, QtiValue>;
+  allowedUndeclaredResponseIdentifiers: ReadonlySet<string>;
+  random: () => number;
+  customOperators: QtiCustomOperatorRegistry;
+  evaluate(expression: QtiProcessingExpression): QtiValue;
+  indexValue(identifierOrInteger: string): number | undefined;
+  numericOperands(expressions: QtiProcessingExpression[]): number[] | null;
+  undeclaredResponseValue(identifier: string): QtiValue | undefined;
+}
+
+export interface EvaluationOptions {
+  allowedUndeclaredResponseIdentifiers?: ReadonlySet<string> | readonly string[] | undefined;
+}
+
+export function createEvaluationContext(
+  document: QtiDocument,
+  responses: Record<string, QtiValue>,
+  outcomes: Record<string, QtiValue>,
+  templateValues: Record<string, QtiValue>,
+  correctResponses: Record<string, QtiValue>,
+  random: () => number,
+  customOperators: QtiCustomOperatorRegistry,
+  options: EvaluationOptions = {},
+): EvaluationContext {
+  const allowedUndeclaredResponseIdentifiers =
+    options.allowedUndeclaredResponseIdentifiers instanceof Set
+      ? options.allowedUndeclaredResponseIdentifiers
+      : new Set(options.allowedUndeclaredResponseIdentifiers ?? []);
+  const context: EvaluationContext = {
+    document,
+    responses,
+    outcomes,
+    templateValues,
+    correctResponses,
+    allowedUndeclaredResponseIdentifiers,
+    random,
+    customOperators,
+    evaluate(expression) {
+      return evaluateProcessingExpression(expression, context);
+    },
+    indexValue(identifierOrInteger) {
+      const parsed = Number(identifierOrInteger);
+      if (Number.isInteger(parsed)) return parsed;
+      const value = outcomes[identifierOrInteger] ?? templateValues[identifierOrInteger] ?? null;
+      const numeric = numericValueOrNull(value);
+      return numeric !== null && Number.isInteger(numeric) ? numeric : undefined;
+    },
+    numericOperands(expressions) {
+      const numericValues: number[] = [];
+      for (const expression of expressions) {
+        const value = context.evaluate(expression);
+        if (value === null || isRecordValue(value)) return null;
+        const values = Array.isArray(value) ? value : [value];
+        for (const item of values) {
+          const numeric = numericValueOrNull(item);
+          if (numeric === null) return null;
+          numericValues.push(numeric);
+        }
+      }
+      return numericValues;
+    },
+    undeclaredResponseValue(identifier) {
+      return allowedUndeclaredResponseIdentifiers.has(identifier) && identifier in responses
+        ? (responses[identifier] ?? null)
+        : undefined;
+    },
+  };
+  return context;
+}
+
+export function evaluateProcessingExpression(
+  expression: QtiProcessingExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "baseValue":
+      return expression.value;
+    case "null":
+      return null;
+    case "randomInteger": {
+      const step = expression.step > 0 ? expression.step : 1;
+      const count = Math.floor((expression.max - expression.min) / step) + 1;
+      return expression.min + Math.floor(context.random() * count) * step;
+    }
+    case "randomFloat":
+      return expression.min + context.random() * (expression.max - expression.min);
+    case "random":
+      if (expression.values.length === 0) return null;
+      return context.evaluate(
+        expression.values[Math.floor(context.random() * expression.values.length)]!,
+      );
+    case "isNull":
+    case "matchCorrect":
+    case "mapResponse":
+    case "mapResponsePoint":
+    case "correct":
+    case "default":
+    case "variable":
+      return evaluateVariableExpression(expression, context);
+    case "multiple":
+    case "ordered":
+    case "index":
+    case "containerSize":
+      return evaluateCollectionExpression(expression, context);
+    case "sum":
+    case "product":
+    case "min":
+    case "max":
+    case "subtract":
+    case "divide":
+    case "power":
+    case "integerDivide":
+    case "integerModulus":
+    case "round":
+    case "roundTo":
+    case "truncate":
+    case "integerToFloat":
+    case "gcd":
+    case "lcm":
+    case "mathConstant":
+    case "mathOperator":
+    case "statsOperator":
+      return evaluateNumericExpression(expression, context);
+    case "and":
+    case "anyN":
+    case "or":
+    case "not":
+      return evaluateBooleanExpression(expression, context);
+    case "match":
+    case "equal":
+    case "equalRounded":
+    case "numericCompare":
+    case "durationCompare":
+    case "member":
+    case "delete":
+    case "contains":
+      return evaluateComparisonExpression(expression, context);
+    case "stringMatch":
+    case "substring":
+    case "patternMatch":
+    case "fieldValue":
+      return evaluateStringExpression(expression, context);
+    case "inside":
+      return evaluateGeometryExpression(expression, context);
+    case "repeat":
+      return evaluateRepeatExpression(expression, context);
+    case "customOperator":
+      return evaluateCustomOperatorExpression(expression, context);
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-expression-children.ts

@@ -0,0 +1,69 @@
+import type { QtiProcessingExpression } from "./types.js";
+import { assertNever } from "./assert-never.js";
+
+export function expressionChildren(expression: QtiProcessingExpression): QtiProcessingExpression[] {
+  switch (expression.type) {
+    case "random":
+      return expression.values;
+    case "multiple":
+    case "ordered":
+    case "sum":
+    case "product":
+    case "min":
+    case "max":
+    case "and":
+    case "anyN":
+    case "or":
+    case "gcd":
+    case "lcm":
+    case "mathOperator":
+    case "repeat":
+    case "customOperator":
+      return expression.expressions;
+    case "subtract":
+    case "divide":
+    case "power":
+    case "integerDivide":
+    case "integerModulus":
+    case "match":
+    case "equal":
+    case "equalRounded":
+    case "numericCompare":
+    case "durationCompare":
+    case "stringMatch":
+    case "substring":
+      return [expression.left, expression.right];
+    case "not":
+    case "round":
+    case "roundTo":
+    case "truncate":
+    case "integerToFloat":
+    case "index":
+    case "containerSize":
+    case "patternMatch":
+    case "fieldValue":
+    case "inside":
+    case "statsOperator":
+      return [expression.expression];
+    case "member":
+    case "delete":
+      return [expression.value, expression.collection];
+    case "contains":
+      return [expression.collection, expression.values];
+    case "baseValue":
+    case "correct":
+    case "default":
+    case "isNull":
+    case "mapResponse":
+    case "mapResponsePoint":
+    case "matchCorrect":
+    case "mathConstant":
+    case "null":
+    case "randomFloat":
+    case "randomInteger":
+    case "variable":
+      return [];
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-mapping.ts

@@ -0,0 +1,153 @@
+import type { QtiDocument, QtiResponseDeclaration, QtiValue } from "./types.js";
+import { qtiScalarToString, qtiValueToStringList } from "./value-format.js";
+import { isRecordValue, numericValue, valuesEqual } from "./processing-values.js";
+
+export function lookupOutcomeValue(
+  document: QtiDocument,
+  identifier: string,
+  value: QtiValue,
+): QtiValue {
+  const declaration = document.item.outcomeDeclarations.find(
+    (outcome) => outcome.identifier === identifier,
+  );
+  const lookupTable = declaration?.lookupTable;
+  if (!lookupTable) return null;
+  if (value === null) return lookupTable.defaultValue;
+  const numeric = numericValue(value);
+  if (lookupTable.type === "match") {
+    return (
+      lookupTable.entries.find((entry) => entry.sourceValue === numeric)?.targetValue ??
+      lookupTable.defaultValue
+    );
+  }
+  const entry = [...lookupTable.entries]
+    .toSorted((left, right) => left.sourceValue - right.sourceValue)
+    .find(
+      (candidate) =>
+        numeric < candidate.sourceValue ||
+        (candidate.includeBoundary !== false && numeric === candidate.sourceValue),
+    );
+  return entry?.targetValue ?? lookupTable.defaultValue;
+}
+
+export function mapOrMatchResponse(
+  declaration: QtiResponseDeclaration,
+  response: QtiValue,
+  correctResponse: QtiValue,
+): number {
+  if (declaration.areaMapping) return scoreAreaMapping(response, declaration.areaMapping);
+  if (declaration.mapping) return scoreMapping(response, declaration.mapping);
+  return valuesEqual(response, correctResponse, declaration.cardinality === "ordered") ? 1 : 0;
+}
+
+export function scoreAreaMapping(
+  response: QtiValue,
+  areaMapping: NonNullable<QtiResponseDeclaration["areaMapping"]>,
+): number {
+  const points = Array.isArray(response)
+    ? response.map(qtiScalarToString)
+    : response === null
+      ? []
+      : qtiValueToStringList(response);
+  let score = 0;
+  for (const point of points) {
+    const parsed = parsePoint(point);
+    if (!parsed) {
+      score += areaMapping.defaultValue;
+      continue;
+    }
+    const entry = areaMapping.entries.find((candidate) => pointInsideArea(parsed, candidate));
+    score += entry?.mappedValue ?? areaMapping.defaultValue;
+  }
+  return clampMappedScore(score, areaMapping.attributes);
+}
+
+export function parsePoint(value: string): { x: number; y: number } | undefined {
+  const [x, y] = value
+    .trim()
+    .split(/[,\s]+/)
+    .map((part) => Number(part));
+  if (x === undefined || y === undefined || !Number.isFinite(x) || !Number.isFinite(y)) {
+    return undefined;
+  }
+  return { x, y };
+}
+
+export function pointInsideArea(
+  point: { x: number; y: number },
+  entry: NonNullable<QtiResponseDeclaration["areaMapping"]>["entries"][number],
+): boolean {
+  if (entry.shape === "circle") {
+    const [cx, cy, radius] = entry.coords;
+    if (cx === undefined || cy === undefined || radius === undefined) return false;
+    return Math.hypot(point.x - cx, point.y - cy) <= radius;
+  }
+
+  if (entry.shape === "rect") {
+    const [left, top, right, bottom] = entry.coords;
+    if (left === undefined || top === undefined || right === undefined || bottom === undefined) {
+      return false;
+    }
+    return point.x >= left && point.x <= right && point.y >= top && point.y <= bottom;
+  }
+
+  if (entry.shape === "poly") {
+    return pointInsidePolygon(point, entry.coords);
+  }
+
+  return false;
+}
+
+function pointInsidePolygon(point: { x: number; y: number }, coords: number[]): boolean {
+  if (coords.length < 6 || coords.length % 2 !== 0) return false;
+  let inside = false;
+  for (let index = 0, previous = coords.length - 2; index < coords.length; index += 2) {
+    const xi = coords[index]!;
+    const yi = coords[index + 1]!;
+    const xj = coords[previous]!;
+    const yj = coords[previous + 1]!;
+    const intersects =
+      yi > point.y !== yj > point.y && point.x < ((xj - xi) * (point.y - yi)) / (yj - yi) + xi;
+    if (intersects) inside = !inside;
+    previous = index;
+  }
+  return inside;
+}
+
+function scoreMapping(
+  response: QtiValue,
+  mapping: NonNullable<QtiResponseDeclaration["mapping"]>,
+): number {
+  const values = Object.fromEntries(
+    mapping.entries
+      .filter((entry) => entry.mapKey !== undefined)
+      .map((entry) => [entry.mapKey!, entry.mappedValue]),
+  );
+  if (Array.isArray(response)) {
+    const score = response.reduce<number>(
+      (sum, value) => sum + (values[String(value)] ?? mapping.defaultValue),
+      0,
+    );
+    return clampMappedScore(score, mapping.attributes);
+  }
+  const score =
+    response === null || isRecordValue(response)
+      ? 0
+      : (values[String(response)] ?? mapping.defaultValue);
+  return clampMappedScore(score, mapping.attributes);
+}
+
+function clampMappedScore(score: number, attributes: Record<string, string>): number {
+  const lower = numericBound(attributes["lower-bound"]);
+  const upper = numericBound(attributes["upper-bound"]);
+  let clamped = score;
+  if (lower !== undefined) clamped = Math.max(clamped, lower);
+  if (upper !== undefined) clamped = Math.min(clamped, upper);
+  return clamped;
+}
+
+function numericBound(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const numberValue = Number(value);
+  return Number.isFinite(numberValue) ? numberValue : undefined;
+}

package/src/processing-operators.ts

@@ -0,0 +1,184 @@
+import type { QtiValue } from "./types.js";
+
+export const MATH_OPERATOR_NAMES = [
+  "abs",
+  "acos",
+  "acot",
+  "acsc",
+  "asec",
+  "asin",
+  "atan",
+  "atan2",
+  "ceil",
+  "cos",
+  "cosh",
+  "cot",
+  "coth",
+  "csc",
+  "csch",
+  "exp",
+  "floor",
+  "ln",
+  "log",
+  "sec",
+  "sech",
+  "signum",
+  "sin",
+  "sinh",
+  "tan",
+  "tanh",
+  "toDegrees",
+  "toRadians",
+] as const;
+
+export const STATS_OPERATOR_NAMES = [
+  "mean",
+  "sampleVariance",
+  "sampleSD",
+  "popVariance",
+  "popSD",
+] as const;
+
+export function roundToDecimalPlaces(value: number, figures: number): number {
+  const factor = 10 ** figures;
+  return Math.round(value * factor) / factor;
+}
+
+export function roundToSignificantFigures(value: number, figures: number): number {
+  if (value === 0 || figures <= 0) return 0;
+  const factor = 10 ** (figures - 1 - Math.floor(Math.log10(Math.abs(value))));
+  return Math.round(value * factor) / factor;
+}
+
+export function roundWithMode(value: number, roundingMode: string, figures: number): number | null {
+  if (!Number.isFinite(value)) return null;
+  if (roundingMode === "decimalPlaces") return roundToDecimalPlaces(value, figures);
+  if (roundingMode === "significantFigures") return roundToSignificantFigures(value, figures);
+  return null;
+}
+
+export function generalizedGcd(values: number[]): number {
+  let result = 0;
+  for (const value of values) {
+    result = gcd(result, Math.abs(value));
+  }
+  return result;
+}
+
+export function generalizedLcm(values: number[]): number {
+  if (values.some((value) => value === 0)) return 0;
+  return values.reduce((result, value) => lcm(result, Math.abs(value)), 1);
+}
+
+function gcd(left: number, right: number): number {
+  let a = Math.abs(left);
+  let b = Math.abs(right);
+  while (b !== 0) {
+    const next = a % b;
+    a = b;
+    b = next;
+  }
+  return a;
+}
+
+function lcm(left: number, right: number): number {
+  return Math.abs(left * right) / gcd(left, right);
+}
+
+export function mathOperatorValue(name: string, values: number[]): QtiValue {
+  const [first, second] = values;
+  if (first === undefined) return null;
+  switch (name) {
+    case "abs":
+      return finiteOrNull(Math.abs(first));
+    case "acos":
+      return Math.abs(first) > 1 ? null : finiteOrNull(Math.acos(first));
+    case "acot":
+      return finiteOrNull(Math.PI / 2 - Math.atan(1 / first));
+    case "acsc":
+      return Math.abs(first) < 1 ? null : finiteOrNull(Math.PI / 2 - Math.asin(1 / first));
+    case "asec":
+      return Math.abs(first) < 1 ? null : finiteOrNull(Math.PI / 2 - Math.acos(1 / first));
+    case "asin":
+      return Math.abs(first) > 1 ? null : finiteOrNull(Math.asin(first));
+    case "atan":
+      return finiteOrNull(Math.atan(first));
+    case "atan2":
+      return second === undefined ? null : finiteOrNull(Math.atan2(first, second));
+    case "ceil":
+      return finiteOrNull(Math.ceil(first));
+    case "cos":
+      return finiteOrNull(Math.cos(first));
+    case "cosh":
+      return finiteOrNull(Math.cosh(first));
+    case "cot":
+      return finiteOrNull(1 / Math.tan(first));
+    case "coth":
+      return finiteOrNull(1 / Math.tanh(first));
+    case "csc":
+      return finiteOrNull(1 / Math.sin(first));
+    case "csch":
+      return finiteOrNull(1 / Math.sinh(first));
+    case "exp":
+      return finiteOrNull(Math.exp(first));
+    case "floor":
+      return finiteOrNull(Math.floor(first));
+    case "ln":
+      return first < 0 ? null : finiteOrNull(Math.log(first));
+    case "log":
+      return first < 0 ? null : finiteOrNull(Math.log10(first));
+    case "sec":
+      return finiteOrNull(1 / Math.cos(first));
+    case "sech":
+      return finiteOrNull(1 / Math.cosh(first));
+    case "signum":
+      return finiteOrNull(Math.sign(first));
+    case "sin":
+      return finiteOrNull(Math.sin(first));
+    case "sinh":
+      return finiteOrNull(Math.sinh(first));
+    case "tan":
+      return finiteOrNull(Math.tan(first));
+    case "tanh":
+      return finiteOrNull(Math.tanh(first));
+    case "toDegrees":
+      return finiteOrNull((first * 180) / Math.PI);
+    case "toRadians":
+      return finiteOrNull((first * Math.PI) / 180);
+    default:
+      return null;
+  }
+}
+
+export function statsOperatorValue(name: string, values: number[]): QtiValue {
+  if (values.length === 0) return 0;
+  const meanValue = mean(values);
+  const squareDiffs = values.map((value) => (value - meanValue) ** 2);
+  switch (name) {
+    case "mean":
+      return meanValue;
+    case "sampleVariance":
+      return meanWithDivisor(squareDiffs, values.length > 1 ? values.length - 1 : 1);
+    case "sampleSD":
+      return Math.sqrt(meanWithDivisor(squareDiffs, values.length > 1 ? values.length - 1 : 1));
+    case "popVariance":
+      return mean(squareDiffs);
+    case "popSD":
+      return Math.sqrt(mean(squareDiffs));
+    default:
+      return null;
+  }
+}
+
+function mean(values: number[]): number {
+  return meanWithDivisor(values, values.length);
+}
+
+function meanWithDivisor(values: number[], divisor: number): number {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, value) => sum + value, 0) / divisor;
+}
+
+function finiteOrNull(value: number): QtiValue {
+  return Number.isFinite(value) ? value : null;
+}

package/src/processing-random.ts

@@ -0,0 +1,16 @@
+export function seededRandom(seed: string | number): () => number {
+  let state = typeof seed === "number" ? seed >>> 0 : hashSeed(seed);
+  return () => {
+    state = (1664525 * state + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+}
+
+function hashSeed(seed: string): number {
+  let hash = 2166136261;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}