@longsightgroup/qti3-core 0.9.2 → 0.9.4

package/src/processing-evaluator-string.ts

@@ -0,0 +1,60 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { qtiValueToString } from "./value-format.js";
+import { isRecordValue, stringMatch } from "./processing-values.js";
+import { resolveOptionalVariableValue } from "./processing-variables.js";
+
+type StringExpression = Extract<
+  QtiProcessingExpression,
+  { type: "stringMatch" | "substring" | "patternMatch" | "fieldValue" }
+>;
+
+export function evaluateStringExpression(
+  expression: StringExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "stringMatch":
+      return stringMatch(
+        context.evaluate(expression.left),
+        context.evaluate(expression.right),
+        expression.caseSensitive,
+        expression.substring,
+      );
+    case "substring":
+      return stringMatch(
+        context.evaluate(expression.right),
+        context.evaluate(expression.left),
+        expression.caseSensitive,
+        true,
+      );
+    case "patternMatch": {
+      const value = context.evaluate(expression.expression);
+      if (value === null) return null;
+      const patternValue =
+        resolveOptionalVariableValue(
+          context.document,
+          expression.pattern,
+          context.responses,
+          context.outcomes,
+          context.templateValues,
+        ) ??
+        context.undeclaredResponseValue(expression.pattern) ??
+        expression.pattern;
+      try {
+        return new RegExp(
+          typeof patternValue === "string" ? patternValue : qtiValueToString(patternValue),
+        ).test(qtiValueToString(value));
+      } catch {
+        return null;
+      }
+    }
+    case "fieldValue": {
+      const value = context.evaluate(expression.expression);
+      return isRecordValue(value) ? (value[expression.fieldIdentifier] ?? null) : null;
+    }
+    default:
+      return assertNever(expression);
+  }
+}

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;
+}