@conform-ed/qti-react 0.0.14 → 0.0.16

package/src/response-validity.ts

@@ -0,0 +1,163 @@
+/**
+ * Response validity (ItemSessionControl validate-responses): "An invalid response is
+ * defined to be a response which does not satisfy the constraints imposed by the
+ * interaction with which it is associated." The constraint vocabulary is what the
+ * view model carries on interaction nodes — min/max-choices, min/max-associations,
+ * min-strings, pattern-mask, min-plays. Only authored attributes are validated:
+ * rendering defaults (e.g. a radio group's single choice) are interaction behavior,
+ * not submission constraints.
+ */
+
+import { compile as compileXsdPattern } from "xspattern";
+
+import { isInteractionKind, v0ContentModel } from "./content-model";
+import type { BodyNode } from "./runtime";
+import { isResponseRecord } from "./types";
+import type { ResponseValue } from "./types";
+
+export type ResponseConstraintKind =
+  | "minChoices"
+  | "maxChoices"
+  | "minAssociations"
+  | "maxAssociations"
+  | "minStrings"
+  | "patternMask"
+  | "minPlays";
+
+export interface InteractionConstraint {
+  readonly responseIdentifier: string;
+  readonly kind: ResponseConstraintKind;
+  /** The declared bound: a count for the min/max constraints, the XSD regex for patternMask. */
+  readonly bound: number | string;
+}
+
+/** A constraint the current response fails — the reason a submission is invalid. */
+export type ResponseViolation = InteractionConstraint;
+
+const countConstraintKinds = ["minChoices", "maxChoices", "minAssociations", "maxAssociations", "minStrings"] as const;
+
+/**
+ * Walk the item body and collect the constraint attributes its interactions carry.
+ * Zero bounds impose nothing: "If max-choices is 0 then there is no restriction";
+ * "If min-choices is 0 then the candidate is not required to select any choices."
+ */
+export function collectInteractionConstraints(content: readonly BodyNode[] | undefined): InteractionConstraint[] {
+  const constraints: InteractionConstraint[] = [];
+
+  function walk(node: BodyNode): void {
+    const record = node as unknown as Record<string, unknown>;
+
+    if (isInteractionKind(v0ContentModel, node.kind) && typeof record["responseIdentifier"] === "string") {
+      const responseIdentifier = record["responseIdentifier"];
+
+      for (const kind of [...countConstraintKinds, "minPlays"] as const) {
+        const bound = record[kind];
+
+        if (typeof bound === "number" && bound > 0) {
+          constraints.push({ responseIdentifier, kind, bound });
+        }
+      }
+
+      const patternMask = record["patternMask"];
+
+      if (typeof patternMask === "string" && patternMask !== "") {
+        constraints.push({ responseIdentifier, kind: "patternMask", bound: patternMask });
+      }
+
+      return; // interactions do not nest
+    }
+
+    for (const key of ["content", "children"] as const) {
+      const nested = record[key];
+
+      if (Array.isArray(nested)) {
+        for (const child of nested as readonly BodyNode[]) {
+          walk(child);
+        }
+      }
+    }
+  }
+
+  for (const node of content ?? []) {
+    walk(node);
+  }
+
+  return constraints;
+}
+
+/** Selected members of a response: choices picked, associations made, strings entered. */
+function memberCount(value: ResponseValue): number {
+  if (value === null || value === undefined || value === "") {
+    return 0;
+  }
+
+  if (Array.isArray(value)) {
+    return value.filter((member) => member !== null && member !== "").length;
+  }
+
+  return 1;
+}
+
+/** The non-empty strings a pattern mask applies to (each container member must match). */
+function stringMembers(value: ResponseValue): string[] {
+  if (typeof value === "string") {
+    return value === "" ? [] : [value];
+  }
+
+  if (Array.isArray(value)) {
+    return value.filter((member): member is string => typeof member === "string" && member !== "");
+  }
+
+  return [];
+}
+
+function violates(constraint: InteractionConstraint, value: ResponseValue): boolean {
+  switch (constraint.kind) {
+    case "minChoices":
+    case "minAssociations":
+    case "minStrings":
+      return memberCount(value) < Number(constraint.bound);
+    case "maxChoices":
+    case "maxAssociations":
+      return memberCount(value) > Number(constraint.bound);
+    case "minPlays": {
+      // "Failure to play the media object the minimum number of times constitutes an
+      // invalid response." The media response variable counts the plays.
+      const plays = typeof value === "number" ? value : 0;
+
+      return plays < Number(constraint.bound);
+    }
+    case "patternMask": {
+      // "the pattern-mask specifies a regular expression that the candidate's
+      // response must match in order to be considered valid" — XSD regex dialect.
+      // An unanswered interaction is governed by the min* constraints, not the
+      // pattern, and an uncompilable pattern never blocks the candidate.
+      const members = stringMembers(value);
+
+      if (members.length === 0) {
+        return false;
+      }
+
+      try {
+        const matches = compileXsdPattern(String(constraint.bound), { language: "xsd" });
+
+        return !members.every((member) => matches(member));
+      } catch {
+        return false;
+      }
+    }
+  }
+}
+
+/** The constraints the current responses fail; empty means the responses are valid. */
+export function collectResponseViolations(
+  constraints: readonly InteractionConstraint[],
+  responses: Readonly<Record<string, ResponseValue>>,
+): ResponseViolation[] {
+  return constraints.filter((constraint) => {
+    const value = responses[constraint.responseIdentifier] ?? null;
+
+    // Record responses (PCI-style composites) carry no countable selection.
+    return !isResponseRecord(value) && violates(constraint, value);
+  });
+}

package/src/rp/evaluate.ts

@@ -6,6 +6,8 @@
  * response processing must stay deterministic and replayable.
  */
 
+import { compile as compileXsdPattern } from "xspattern";
+
 import { parseCoords, parsePoint, pointInShape } from "../graphic";
 import { mapResponse, mapResponsePoint } from "../response-processing";
 import type { ResponseDeclarationView, ResponseValue } from "../types";
@@ -32,8 +34,13 @@ export interface EvalEnv {
   readonly random?: (() => number) | undefined;
   /** `testVariables` aggregation; present only in test-level outcome processing. */
   readonly testVariables?: (expression: RpExpressionView) => MaybeRpValue;
-  /** The `number*` item-session aggregates; present only in test-level outcome processing. */
+  /**
+   * The test-level subset aggregates (`number*`, `outcomeMinimum`/`outcomeMaximum`);
+   * present only in test-level outcome processing.
+   */
   readonly testAggregate?: (expression: RpExpressionView) => MaybeRpValue;
+  /** Declared default of any item variable, for the `default` expression (§2.11.1.3). */
+  readonly variableDefault?: (identifier: string) => MaybeRpValue;
   /** Registered vendor operators by class; unregistered classes stay unsupported. */
   readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }
@@ -41,10 +48,16 @@ export interface EvalEnv {
 /** Expression kinds legal everywhere (deterministic). */
 export const deterministicExpressionKinds: ReadonlySet<string> = new Set([
   "and",
+  "anyN",
   "baseValue",
+  "containerSize",
+  "contains",
   "correct",
+  "default",
   "delete",
   "divide",
+  "durationGte",
+  "durationLt",
   "equal",
   "equalRounded",
   "fieldValue",
@@ -70,8 +83,11 @@ export const deterministicExpressionKinds: ReadonlySet<string> = new Set([
   "min",
   "multiple",
   "not",
+  "null",
   "or",
   "ordered",
+  "patternMatch",
+  "power",
   "product",
   "repeat",
   "round",
@@ -99,6 +115,36 @@ export class RpUnsupportedError extends Error {
 
 const mathConstants: Readonly<Record<string, number>> = { pi: Math.PI, e: Math.E };
 
+/**
+ * Compiled XSD-dialect pattern matchers (`patternMatch` uses the regular expression
+ * language of Appendix F of XML Schema, not ECMAScript). null caches a pattern that
+ * failed to compile — invalid patterns are refused, never guessed.
+ */
+const xsdPatternMatchers = new Map<string, ((value: string) => boolean) | null>();
+
+function xsdPatternMatcher(pattern: string): ((value: string) => boolean) | null {
+  const cached = xsdPatternMatchers.get(pattern);
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  let matcher: ((value: string) => boolean) | null;
+
+  try {
+    matcher = compileXsdPattern(pattern);
+  } catch {
+    matcher = null;
+  }
+
+  xsdPatternMatchers.set(pattern, matcher);
+
+  return matcher;
+}
+
+/** The brace-enclosed variable-reference form of string attributes (§7.13). */
+const encVariableStringPattern = /^\{[^{}]+\}$/u;
+
 /** The named functions of `mathOperator`; undefined means the name is unknown. */
 function applyMathOperator(name: string, x: number, y: number): number | undefined {
   switch (name) {
@@ -163,6 +209,28 @@ function applyMathOperator(name: string, x: number, y: number): number | undefin
   }
 }
 
+/**
+ * A numeric attribute that is either a literal or a variable reference (the spec's
+ * IntOrIdentifier / FloatOrVariableRef): "If n is an identifier, it is the value of n
+ * at runtime that is used" (QTI 3 info model §2.11.3.6). The brace-enclosed
+ * EncVariableString form (§7.13) is accepted alongside bare identifiers. An
+ * unresolvable or NULL-valued reference yields null — the operator then results in
+ * NULL, never a refusal.
+ */
+function resolveNumericAttribute(raw: number | string | undefined, env: EvalEnv): number | null | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+
+  if (typeof raw === "number") {
+    return raw;
+  }
+
+  const identifier = raw.startsWith("{") && raw.endsWith("}") ? raw.slice(1, -1) : raw;
+
+  return singleNumber(env.lookupVariable(identifier));
+}
+
 function roundToFigures(value: number, mode: "decimalPlaces" | "significantFigures", figures: number): number | null {
   if (mode === "decimalPlaces") {
     const scale = 10 ** figures;
@@ -270,12 +338,21 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
     case "or": {
       const members = (expression.expressions ?? []).map((child) => singleBoolean(evaluate(child)));
 
-      // NULL operands are treated as false; sufficient for the supported coverage.
-      return booleanValue(
-        expression.kind === "and"
-          ? members.every((member) => member === true)
-          : members.some((member) => member === true),
-      );
+      // Three-valued logic (§2.11.3.10/.15): a decisive operand wins outright; an
+      // undecided one ("NULL and all others are true/false") makes the result NULL.
+      if (expression.kind === "and") {
+        if (members.some((member) => member === false)) {
+          return booleanValue(false);
+        }
+
+        return members.some((member) => member === null) ? null : booleanValue(true);
+      }
+
+      if (members.some((member) => member === true)) {
+        return booleanValue(true);
+      }
+
+      return members.some((member) => member === null) ? null : booleanValue(false);
     }
 
     case "sum":
@@ -344,12 +421,12 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         return booleanValue(a === b);
       }
 
-      const t0 = expression.tolerance?.[0];
-      const t1 = expression.tolerance?.[1] ?? t0;
+      const t0 = resolveNumericAttribute(expression.tolerance?.[0], env);
+      const t1raw = expression.tolerance?.[1];
+      const t1 = t1raw === undefined ? t0 : resolveNumericAttribute(t1raw, env);
 
       if (typeof t0 !== "number" || typeof t1 !== "number") {
-        // Template-variable tolerances (and missing ones) are out of the staged scope.
-        throw new RpUnsupportedError("equal");
+        return null; // missing or unresolvable tolerance → NULL
       }
 
       const lower = mode === "absolute" ? a - t0 : a * (1 - t0 / 100);
@@ -376,8 +453,10 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
     }
 
     case "index": {
-      if (typeof expression.n !== "number") {
-        throw new RpUnsupportedError("index"); // template-variable n is out of scope
+      const n = resolveNumericAttribute(expression.n, env);
+
+      if (typeof n !== "number") {
+        return null; // missing or unresolvable n → NULL
       }
 
       const operand = expression.expressions?.[0];
@@ -387,7 +466,7 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         return null;
       }
 
-      const member = container.values[expression.n - 1];
+      const member = container.values[n - 1];
 
       if (member === undefined) {
         return null; // out of range is null, per spec
@@ -503,8 +582,10 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
     }
 
     case "roundTo": {
-      if (typeof expression.figures !== "number") {
-        throw new RpUnsupportedError("roundTo"); // template-variable figures
+      const figures = resolveNumericAttribute(expression.figures, env);
+
+      if (typeof figures !== "number") {
+        return null; // missing or unresolvable figures → NULL
       }
 
       const operand = expression.expressions?.[0];
@@ -514,14 +595,16 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         return null;
       }
 
-      const rounded = roundToFigures(value, expression.roundingMode ?? "significantFigures", expression.figures);
+      const rounded = roundToFigures(value, expression.roundingMode ?? "significantFigures", figures);
 
       return rounded === null ? null : floatValue(rounded);
     }
 
     case "equalRounded": {
-      if (typeof expression.figures !== "number") {
-        throw new RpUnsupportedError("equalRounded");
+      const figures = resolveNumericAttribute(expression.figures, env);
+
+      if (typeof figures !== "number") {
+        return null; // missing or unresolvable figures → NULL
       }
 
       const [a, b] = (expression.expressions ?? []).map((child) => singleNumber(evaluate(child)));
@@ -531,8 +614,8 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
       }
 
       const mode = expression.roundingMode ?? "significantFigures";
-      const roundedA = roundToFigures(a, mode, expression.figures);
-      const roundedB = roundToFigures(b, mode, expression.figures);
+      const roundedA = roundToFigures(a, mode, figures);
+      const roundedB = roundToFigures(b, mode, figures);
 
       return roundedA === null || roundedB === null ? null : booleanValue(roundedA === roundedB);
     }
@@ -608,18 +691,18 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
     }
 
     case "repeat": {
-      if (typeof expression.numberRepeats !== "number") {
-        throw new RpUnsupportedError("repeat"); // template-variable count
-      }
+      const numberRepeats = resolveNumericAttribute(expression.numberRepeats, env);
 
-      if (expression.numberRepeats < 1) {
+      // "If qti-number-repeats refers to a variable whose value is less than 1, the
+      // value of the whole expression is NULL" (§2.11.3.42); unresolvable refs too.
+      if (typeof numberRepeats !== "number" || numberRepeats < 1) {
         return null;
       }
 
       const members: RpValue["values"][number][] = [];
       let baseType: string | undefined;
 
-      for (let pass = 0; pass < expression.numberRepeats; pass += 1) {
+      for (let pass = 0; pass < numberRepeats; pass += 1) {
         for (const child of expression.expressions ?? []) {
           const value = evaluate(child);
 
@@ -635,6 +718,160 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
       return members.length === 0 ? null : rpValue("ordered", members, baseType);
     }
 
+    case "null":
+      return null;
+
+    case "durationGte":
+    case "durationLt": {
+      // Durations are compared as elapsed seconds; "longer (or equal, within the
+      // limits imposed by truncation …)" (§2.11.3.20/.21). NULL operands propagate.
+      const [a, b] = (expression.expressions ?? []).map((child) => singleNumber(evaluate(child)));
+
+      if (a === undefined || b === undefined || a === null || b === null) {
+        return null;
+      }
+
+      return booleanValue(expression.kind === "durationGte" ? a >= b : a < b);
+    }
+
+    case "default":
+      // "Returns the associated qti-default-value or NULL if no default value was
+      // declared" (§2.11.1.3).
+      return env.variableDefault?.(expression.identifier ?? "") ?? null;
+
+    case "patternMatch": {
+      const operand = expression.expressions?.[0];
+      const value = operand === undefined ? null : evaluate(operand);
+      const member = value?.values[0];
+
+      if (value === null || typeof member !== "string") {
+        return null; // "If the sub-expression is NULL then the operator results in NULL" (§2.11.3.41)
+      }
+
+      if (expression.pattern === undefined) {
+        throw new RpUnsupportedError("patternMatch");
+      }
+
+      // EncVariableString (§7.13): a brace-enclosed reference resolves the pattern
+      // from a variable at runtime; anything else is a literal XSD pattern.
+      const pattern = encVariableStringPattern.test(expression.pattern)
+        ? env.lookupVariable(expression.pattern.slice(1, -1))?.values[0]
+        : expression.pattern;
+
+      if (typeof pattern !== "string") {
+        return null; // unresolvable pattern reference → NULL
+      }
+
+      const matcher = xsdPatternMatcher(pattern);
+
+      if (matcher === null) {
+        throw new RpUnsupportedError("patternMatch"); // invalid pattern: refuse, never guess
+      }
+
+      return booleanValue(matcher(member));
+    }
+
+    case "power": {
+      const [a, b] = (expression.expressions ?? []).map((child) => singleNumber(evaluate(child)));
+
+      if (a === undefined || b === undefined || a === null || b === null) {
+        return null;
+      }
+
+      const result = a ** b;
+
+      // "If the resulting value is outside the value set defined by float (not
+      // including positive and negative infinity) then the operator shall result in
+      // NULL" (§2.11.3.30).
+      return Number.isFinite(result) ? floatValue(result) : null;
+    }
+
+    case "containerSize": {
+      const operand = expression.expressions?.[0];
+      const container = operand === undefined ? null : evaluate(operand);
+
+      // "If the sub-expression is NULL the result is 0" (§2.11.3.32) — the spec's
+      // exception to NULL propagation; an empty container is NULL in this model.
+      return {
+        cardinality: "single",
+        baseType: "integer",
+        values: [container === null ? 0 : container.values.length],
+      };
+    }
+
+    case "contains": {
+      const [firstExpression, secondExpression] = expression.expressions ?? [];
+
+      if (firstExpression === undefined || secondExpression === undefined) {
+        return null;
+      }
+
+      const first = evaluate(firstExpression);
+      const second = evaluate(secondExpression);
+
+      if (first === null || second === null || first.cardinality === "record" || second.cardinality === "record") {
+        return null;
+      }
+
+      const baseType = first.baseType ?? second.baseType;
+
+      if (first.cardinality === "ordered") {
+        // "For ordered containers the second sub-expression must be a strict
+        // sub-sequence within the first" (§2.11.3.17): a contiguous in-order run.
+        const found = first.values.some(
+          (_, start) =>
+            start + second.values.length <= first.values.length &&
+            second.values.every((member, offset) =>
+              scalarsEqual(first.values[start + offset]!, member, baseType, env.normalization),
+            ),
+        );
+
+        return booleanValue(found);
+      }
+
+      // Unordered: multiset semantics — "[A,B,C] does not contain [B,B] but
+      // [A,B,B,C] does" (§2.11.3.17).
+      const remaining = [...first.values];
+
+      for (const member of second.values) {
+        const at = remaining.findIndex((candidate) => scalarsEqual(candidate, member, baseType, env.normalization));
+
+        if (at === -1) {
+          return booleanValue(false);
+        }
+
+        remaining.splice(at, 1);
+      }
+
+      return booleanValue(true);
+    }
+
+    case "anyN": {
+      const min = resolveNumericAttribute(expression.min, env);
+      const max = resolveNumericAttribute(expression.max, env);
+
+      if (typeof min !== "number" || typeof max !== "number") {
+        return null;
+      }
+
+      const members = (expression.expressions ?? []).map((child) => singleBoolean(evaluate(child)));
+      const trueCount = members.filter((member) => member === true).length;
+      const nullCount = members.filter((member) => member === null).length;
+
+      // The actual count of true lies in [trueCount, trueCount + nullCount]; the
+      // result is decided only when that whole interval is inside or outside
+      // [min, max] — this reproduces the spec's worked examples (§2.11.3, anyN).
+      if (trueCount >= min && trueCount + nullCount <= max) {
+        return booleanValue(true);
+      }
+
+      if (trueCount + nullCount < min || trueCount > max) {
+        return booleanValue(false);
+      }
+
+      return null;
+    }
+
     case "stringMatch":
     case "substring": {
       const [a, b] = (expression.expressions ?? []).map((child) => {
@@ -735,9 +972,9 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         throw new RpUnsupportedError(expression.kind);
       }
 
-      const min = expression.min ?? 0;
-      const max = expression.max ?? min;
-      const step = expression.step ?? 1;
+      const min = resolveNumericAttribute(expression.min, env) ?? 0;
+      const max = resolveNumericAttribute(expression.max, env) ?? min;
+      const step = resolveNumericAttribute(expression.step, env) ?? 1;
       const count = Math.max(1, Math.floor((max - min) / step) + 1);
 
       return { cardinality: "single", baseType: "integer", values: [min + Math.floor(env.random() * count) * step] };
@@ -748,8 +985,8 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
         throw new RpUnsupportedError(expression.kind);
       }
 
-      const min = expression.min ?? 0;
-      const max = expression.max ?? min;
+      const min = resolveNumericAttribute(expression.min, env) ?? 0;
+      const max = resolveNumericAttribute(expression.max, env) ?? min;
 
       return floatValue(min + env.random() * (max - min));
     }
@@ -776,7 +1013,9 @@ export function evaluateExpression(expression: RpExpressionView, env: EvalEnv):
     case "numberIncorrect":
     case "numberPresented":
     case "numberResponded":
-    case "numberSelected": {
+    case "numberSelected":
+    case "outcomeMinimum":
+    case "outcomeMaximum": {
       if (!env.testAggregate) {
         throw new RpUnsupportedError(expression.kind);
       }
@@ -819,6 +1058,15 @@ export function collectExpressionIssues(
     }
   } else if (!allowedKinds.has(expression.kind)) {
     report(expression.kind);
+  } else if (
+    expression.kind === "patternMatch" &&
+    expression.pattern !== undefined &&
+    !encVariableStringPattern.test(expression.pattern) &&
+    xsdPatternMatcher(expression.pattern) === null
+  ) {
+    // A literal pattern that does not compile can never evaluate: surface it at
+    // gate time instead of as a runtime abort.
+    report(expression.kind);
   }
 
   for (const child of expression.expressions ?? []) {

package/src/rp/index.ts

@@ -1,6 +1,7 @@
 export { collectRpIssues, executeResponseProcessing } from "./interpreter";
 export {
   applyCorrectResponseOverrides,
+  applyTemplateDefaultOverrides,
   collectTemplateIssues,
   executeTemplateProcessing,
   mulberry32,
@@ -13,6 +14,10 @@ export {
 export { resolveTemplate } from "./templates";
 export type {
   CustomOperatorImplementation,
+  InterpolationTableEntryView,
+  InterpolationTableView,
+  MatchTableEntryView,
+  MatchTableView,
   MaybeRpValue,
   OutcomeDeclarationView,
   OutcomeValue,