@longsightgroup/qti3-core 0.10.6 → 0.12.0

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type QtiAdaptiveTurnResult,
 } from "./adaptive-turn.js";
 export { assertNever } from "./assert-never.js";
+export { diagnosticKey, uniqueDiagnostics } from "./diagnostics.js";
 export {
   createCatalogSupportResolution,
   type QtiCatalogSupportResolution,
@@ -57,9 +58,13 @@ export {
   discoverQtiPackageContentAssets,
   normalizePackagePath,
   QTI_ITEM_RESOURCE_TYPE,
+  isQtiItemResource,
   QTI_PACKAGE_MANIFEST_PATH,
   parseQtiPackage,
+  parseQtiPackageFromEntries,
   readQtiPackageZipEntries,
+  readQtiPackageZipEntriesAsync,
+  scopeDiagnosticToPackagePath,
   type QtiAssessmentSectionPackageModel,
   type QtiAssessmentTestItemRef,
   type QtiAssessmentTestPackageModel,
@@ -71,11 +76,14 @@ export {
   type QtiPackageEntry,
   type QtiPackageInflateContext,
   type QtiPackageInflateRaw,
+  type QtiPackageInflateRawAsync,
+  type QtiPackageZipAsyncOptions,
   type QtiItemSessionControl,
   type QtiPackageItem,
   type QtiPackageItemSource,
   type QtiPackageParseOptions,
   type QtiPackageParseResult,
+  type QtiPackageXmlFileSummary,
   type QtiPackageResourceLimits,
   type QtiPackageShape,
   type QtiStandardAlignment,
@@ -184,6 +192,7 @@ export {
   type QtiCustomOperatorRegistry,
   type QtiItemSession,
   type QtiItemSessionOptions,
+  type QtiSessionEnvironment,
 } from "./session.js";
 export {
   deprecatedInteractionSupport,
@@ -383,3 +392,32 @@ export {
   formatQtiTextResponse,
   qtiTextResponseString,
 } from "./text-response.js";
+export type {
+  QtiExecutableTest,
+  QtiTestDefinition,
+  QtiTestSection,
+  QtiTestItemRef,
+  QtiTestBranch,
+  QtiTestResult,
+  QtiTestOutcomeRule,
+} from "./test-model.js";
+export { validateQtiTest } from "./test-validation.js";
+export { parseQtiTest } from "./test-parser.js";
+export { parseQtiTestExecution } from "./test-parser.js";
+export type { QtiTestExecution } from "./test-parser.js";
+export {
+  startQtiTest,
+  submitQtiTestAnswer,
+  snapshotQtiTestSession,
+  restoreQtiTestSession,
+} from "./test-session.js";
+export type { QtiTestSession, QtiTestSessionSnapshot } from "./test-session.js";
+export type { QtiTestSubmission } from "./test-processing.js";
+export type { QtiTestExpression, QtiTestBaseType } from "./test-expression.js";
+export { serializeTestExpression } from "./test-expression-serializer.js";
+export { isQtiIdentifier } from "./qti-identifier.js";
+export { isQtiPackageItemHref } from "./qti-package-paths.js";
+export { testFailure } from "./test-model.js";
+export { testExecutionSupport } from "./test-support.js";
+export { inspectQtiBinaryChoice } from "./binary-choice.js";
+export type { QtiBinaryChoicePolicy } from "./binary-choice.js";

package/src/item-submission-materialization.ts

@@ -65,6 +65,7 @@ export function materializeQtiItemSubmission(
     parsedItem: parsedResult.parsed,
     diagnosticPrefix: "itemSubmission",
     allowedUndeclaredResponseIdentifiers: input.allowedUndeclaredResponseIdentifiers,
+    sessionEnvironment: input.sessionEnvironment,
     priorState: priorState.state,
     submission: {
       trustedResponses: input.trustedResponses,
@@ -98,6 +99,7 @@ function materializeAdaptiveSubmission(
     parsedItem,
     diagnosticPrefix: "itemSubmission",
     allowedUndeclaredResponseIdentifiers: input.allowedUndeclaredResponseIdentifiers,
+    sessionEnvironment: input.sessionEnvironment,
     priorState: input.existingState,
     trustedResponses: input.trustedResponses,
     trustedInteractionStates: input.trustedInteractionStates,

package/src/parser-processing.ts

@@ -1,4 +1,10 @@
-import { coerceValue, parseCoords, parseShape, parseXmlBoolean } from "./parser-values.js";
+import {
+  coerceValue,
+  parseCoords,
+  parseInteger,
+  parseShape,
+  parseXmlBoolean,
+} from "./parser-values.js";
 import { responseConditionsFromRules } from "./processing-rules.js";
 import type {
   QtiLookupOutcomeValue,
@@ -215,12 +221,8 @@ function parseExpression(node: XmlNode): QtiProcessingExpression | undefined {
   }
 
   if (node.localName === "qti-is-null") {
-    const variable = childElements(node, "qti-variable")[0];
-    return {
-      type: "isNull",
-      identifier: variable?.attributes.identifier ?? "",
-      source: node.source,
-    };
+    const expression = parseFirstExpression(node);
+    return expression ? { type: "isNull", expression, source: node.source } : undefined;
   }
 
   if (node.localName === "qti-map-response") {
@@ -281,14 +283,8 @@ function parseExpression(node: XmlNode): QtiProcessingExpression | undefined {
   }
 
   if (node.localName === "qti-random") {
-    const multiple = childElements(node, "qti-multiple")[0];
-    return {
-      type: "random",
-      values: childElements(multiple ?? node)
-        .map(parseExpression)
-        .filter((expression): expression is QtiProcessingExpression => expression !== undefined),
-      source: node.source,
-    };
+    const expression = parseFirstExpression(node);
+    return expression ? { type: "random", expression, source: node.source } : undefined;
   }
 
   if (node.localName === "qti-multiple") {
@@ -473,15 +469,16 @@ function parseExpression(node: XmlNode): QtiProcessingExpression | undefined {
     const [left, right] = childElements(node)
       .map(parseExpression)
       .filter((expression): expression is QtiProcessingExpression => expression !== undefined);
-    if (left && right) return { type: "equal", left, right, source: node.source };
+    if (left && right)
+      return { type: "equal", left, right, attributes: node.attributes, source: node.source };
   }
 
   if (node.localName === "qti-equal-rounded") {
     const [left, right] = childElements(node)
       .map(parseExpression)
       .filter((expression): expression is QtiProcessingExpression => expression !== undefined);
-    const roundingMode = node.attributes["rounding-mode"] ?? "";
-    const figures = Number(node.attributes.figures ?? 0);
+    const roundingMode = node.attributes["rounding-mode"] ?? "significantFigures";
+    const figures = parseInteger(node.attributes.figures) ?? node.attributes.figures ?? "";
     if (left && right) {
       return { type: "equalRounded", left, right, roundingMode, figures, source: node.source };
     }

package/src/parser-values.ts

@@ -1,11 +1,11 @@
 import type {
   QtiBaseType,
   QtiCardinality,
-  QtiRecordValue,
   QtiResponseDeclaration,
   QtiScalarValue,
   QtiValue,
 } from "./types.js";
+import { isRecordValue } from "./value-guards.js";
 
 const QTI_BASE_TYPES = new Set<string>([
   "identifier",
@@ -127,7 +127,3 @@ export function parseCoords(value: string | undefined): number[] {
     .map((part) => Number(part.trim()))
     .filter((part) => Number.isFinite(part));
 }
-
-function isRecordValue(value: QtiValue): value is QtiRecordValue {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/parser.ts

@@ -178,6 +178,10 @@ function parseAssessmentItem(node: XmlNode, diagnostics: QtiDiagnostic[]): QtiAs
 
   return {
     identifier,
+    sourceChildren: node.children.map((child) => ({
+      qtiName: child.localName,
+      source: child.source,
+    })),
     title: node.attributes.title,
     language: node.attributes["xml:lang"] ?? node.attributes.lang,
     adaptive: parseXmlBoolean(node.attributes.adaptive) === true,
@@ -213,6 +217,36 @@ function diagnoseProcessingElements(
   if (!processingNode) return;
   for (const node of [processingNode, ...descendants(processingNode, () => true)]) {
     if (!node.localName.startsWith("qti-")) continue;
+    if (
+      node.localName === "qti-pattern-match" &&
+      (node.attributes.pattern === undefined || childElements(node).length !== 1)
+    ) {
+      diagnostics.push({
+        code: "processing.pattern.required",
+        severity: "error",
+        message: "qti-pattern-match requires a pattern attribute and exactly one expression.",
+        path: node.source.path,
+        source: node.source,
+      });
+    }
+    if (node.localName === "qti-is-null" && childElements(node).length !== 1) {
+      diagnostics.push({
+        code: "processing.isNull.arity",
+        severity: "error",
+        message: "qti-is-null requires exactly one expression.",
+        path: node.source.path,
+        source: node.source,
+      });
+    }
+    if (node.localName === "qti-random" && childElements(node).length !== 1) {
+      diagnostics.push({
+        code: "processing.random.arity",
+        severity: "error",
+        message: "qti-random requires exactly one container expression.",
+        path: node.source.path,
+        source: node.source,
+      });
+    }
     if (
       processingNode.localName === "qti-response-processing" &&
       responseProcessingForbiddenNames.has(node.localName)

package/src/processing-equality.ts

@@ -0,0 +1,104 @@
+import { parseFiniteNumber, parseXmlBoolean } from "./parser-values.js";
+import type { QtiDiagnostic, QtiProcessingExpression, QtiValue } from "./types.js";
+
+type EqualExpression = Extract<QtiProcessingExpression, { type: "equal" }>;
+type EqualityTolerance =
+  | { mode: "exact" }
+  | {
+      mode: "absolute" | "relative";
+      lower: string;
+      upper: string;
+      includeLower: boolean;
+      includeUpper: boolean;
+    };
+
+function parseTolerance(
+  attributes: Record<string, string> = {},
+): { ok: true; value: EqualityTolerance } | { ok: false; message: string } {
+  const mode = attributes["tolerance-mode"] ?? "exact";
+  if (mode !== "exact" && mode !== "absolute" && mode !== "relative") {
+    return {
+      ok: false,
+      message: "qti-equal requires exact, absolute, or relative tolerance-mode.",
+    };
+  }
+  const lowerAttribute = attributes["include-lower-bound"];
+  const upperAttribute = attributes["include-upper-bound"];
+  const includeLower = lowerAttribute === undefined ? true : parseXmlBoolean(lowerAttribute);
+  const includeUpper = upperAttribute === undefined ? true : parseXmlBoolean(upperAttribute);
+  if (includeLower === undefined || includeUpper === undefined) {
+    return { ok: false, message: "qti-equal boundary flags must be boolean." };
+  }
+  if (mode === "exact") return { ok: true, value: { mode } };
+  const tolerances = attributes.tolerance?.trim().split(/\s+/) ?? [];
+  const [lower, upper = lower] = tolerances;
+  if (!lower || !upper || tolerances.length > 2) {
+    return {
+      ok: false,
+      message: "qti-equal requires one or two tolerance values in absolute or relative mode.",
+    };
+  }
+  return { ok: true, value: { mode, lower, upper, includeLower, includeUpper } };
+}
+
+/** Validate tolerance attributes and numeric literal or declared-variable operands. */
+export function validateEqualTolerance(
+  expression: EqualExpression,
+  variables: ReadonlySet<string>,
+  diagnostics: QtiDiagnostic[],
+): void {
+  const parsed = parseTolerance(expression.attributes);
+  const messages: string[] = [];
+  if (!parsed.ok) messages.push(parsed.message);
+  else if (parsed.value.mode !== "exact") {
+    for (const token of [parsed.value.lower, parsed.value.upper]) {
+      const number = parseFiniteNumber(token);
+      if (number === undefined ? !variables.has(token) : number < 0) {
+        messages.push(
+          "qti-equal tolerance must be nonnegative numeric values or declared variable references.",
+        );
+        break;
+      }
+    }
+  }
+  for (const message of messages) {
+    diagnostics.push({
+      code: "processing.equal.tolerance",
+      severity: "error",
+      message,
+      source: expression.source,
+      path: expression.source?.path,
+    });
+  }
+}
+
+/** Compare single numeric operands using QTI absolute/relative tolerance and boundary rules. */
+export function equalWithTolerance(
+  expression: EqualExpression,
+  left: QtiValue,
+  right: QtiValue,
+  resolve: (identifier: string) => QtiValue,
+): boolean | null {
+  if (typeof left !== "number" || typeof right !== "number") return null;
+  const parsed = parseTolerance(expression.attributes);
+  if (!parsed.ok) return null;
+  const tolerance = parsed.value;
+  if (tolerance.mode === "exact") return left === right;
+  const lower = parseFiniteNumber(tolerance.lower) ?? resolve(tolerance.lower);
+  const upper = parseFiniteNumber(tolerance.upper) ?? resolve(tolerance.upper);
+  if (
+    typeof lower !== "number" ||
+    typeof upper !== "number" ||
+    !Number.isFinite(lower) ||
+    !Number.isFinite(upper) ||
+    lower < 0 ||
+    upper < 0
+  )
+    return null;
+  const minimum = tolerance.mode === "absolute" ? left - lower : left * (1 - lower / 100);
+  const maximum = tolerance.mode === "absolute" ? left + upper : left * (1 + upper / 100);
+  return (
+    (tolerance.includeLower ? right >= minimum : right > minimum) &&
+    (tolerance.includeUpper ? right <= maximum : right < maximum)
+  );
+}

package/src/processing-evaluator-comparison.ts

@@ -1,4 +1,5 @@
 import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { equalWithTolerance } from "./processing-equality.js";
 import { assertNever } from "./assert-never.js";
 import type { EvaluationContext } from "./processing-evaluator.js";
 import {
@@ -47,22 +48,21 @@ export function evaluateComparisonExpression(
     case "equal": {
       const left = context.evaluate(expression.left);
       const right = context.evaluate(expression.right);
-      return left === null || right === null
-        ? null
-        : valuesEqual(
-            left,
-            right,
-            false,
-            expressionBaseType(expression.left, context.document) ??
-              expressionBaseType(expression.right, context.document),
-          );
+      return equalWithTolerance(expression, left, right, (identifier) =>
+        context.evaluate({ type: "variable", identifier }),
+      );
     }
     case "equalRounded": {
+      const figures =
+        typeof expression.figures === "number"
+          ? expression.figures
+          : context.evaluate({ type: "variable", identifier: expression.figures });
       const validRounding =
-        Number.isInteger(expression.figures) &&
+        typeof figures === "number" &&
+        Number.isInteger(figures) &&
         (expression.roundingMode === "decimalPlaces"
-          ? expression.figures >= 0
-          : expression.roundingMode === "significantFigures" && expression.figures > 0);
+          ? figures >= 0
+          : expression.roundingMode === "significantFigures" && figures > 0);
       if (!validRounding) return null;
       const left = context.evaluate(expression.left);
       const right = context.evaluate(expression.right);
@@ -70,8 +70,8 @@ export function evaluateComparisonExpression(
       const leftNumber = numericValueOrNull(left);
       const rightNumber = numericValueOrNull(right);
       if (leftNumber === null || rightNumber === null) return null;
-      const roundedLeft = roundWithMode(leftNumber, expression.roundingMode, expression.figures);
-      const roundedRight = roundWithMode(rightNumber, expression.roundingMode, expression.figures);
+      const roundedLeft = roundWithMode(leftNumber, expression.roundingMode, figures);
+      const roundedRight = roundWithMode(rightNumber, expression.roundingMode, figures);
       return roundedLeft === null || roundedRight === null ? null : roundedLeft === roundedRight;
     }
     case "numericCompare": {
@@ -123,6 +123,11 @@ export function evaluateComparisonExpression(
       const baseType =
         expressionBaseType(expression.collection, context.document) ??
         expressionBaseType(expression.values, context.document);
+      if (expressionIsOrdered(expression.collection, context.document)) {
+        return collection.some((_, offset) =>
+          valuesEqual(collection.slice(offset, offset + values.length), values, true, baseType),
+        );
+      }
       return containsValues(collection, values, baseType);
     }
     default:

package/src/processing-evaluator-numeric.ts

@@ -9,12 +9,8 @@ import {
   roundToSignificantFigures,
   statsOperatorValue,
 } from "./processing-operators.js";
-import {
-  isRecordValue,
-  numericValue,
-  numericValueOrNull,
-  valueContainer,
-} from "./processing-values.js";
+import { numericValue, numericValueOrNull, valueContainer } from "./processing-values.js";
+import { isRecordValue } from "./value-guards.js";
 
 type NumericExpression = Extract<
   QtiProcessingExpression,

package/src/processing-evaluator-string.ts

@@ -1,9 +1,9 @@
 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";
+import { stringMatch } from "./processing-values.js";
+import { isRecordValue } from "./value-guards.js";
+import { matchXmlSchemaRegex, patternVariableIdentifier } from "./xml-schema-regex.js";
 
 type StringExpression = Extract<
   QtiProcessingExpression,
@@ -32,23 +32,30 @@ export function evaluateStringExpression(
     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 {
+      const reference = patternVariableIdentifier(expression.pattern);
+      const pattern =
+        reference === undefined
+          ? expression.pattern
+          : context.evaluate({ type: "variable", identifier: reference });
+      if (pattern === null) return null;
+      if (typeof value !== "string" || typeof pattern !== "string") {
+        context.diagnostics.push({
+          code: "processing.pattern.type",
+          severity: "error",
+          message: "Pattern matching requires a single string pattern and operand.",
+          source: expression.source,
+        });
         return null;
       }
+      const result = matchXmlSchemaRegex(pattern, value);
+      if (result.ok) return result.matches;
+      context.diagnostics.push({
+        code: `processing.pattern.${result.problem.code}`,
+        severity: "error",
+        message: result.problem.message,
+        source: expression.source,
+      });
+      return null;
     }
     case "fieldValue": {
       const value = context.evaluate(expression.expression);

package/src/processing-evaluator-variable.ts

@@ -29,7 +29,7 @@ export function evaluateVariableExpression(
 ): QtiValue {
   switch (expression.type) {
     case "isNull":
-      return isNullResponse(context.responses[expression.identifier] ?? null);
+      return isNullResponse(context.evaluate(expression.expression));
     case "matchCorrect": {
       const declaration = getResponseDeclaration(context.document, expression.correctIdentifier);
       return declaration
@@ -63,8 +63,12 @@ export function evaluateVariableExpression(
     case "correct":
       return context.correctResponses[expression.identifier] ?? null;
     case "default":
-      return defaultValueForIdentifier(context.document, expression.identifier);
-    case "variable":
+      return Object.hasOwn(context.defaultValues, expression.identifier)
+        ? (context.defaultValues[expression.identifier] ?? null)
+        : defaultValueForIdentifier(context.document, expression.identifier);
+    case "variable": {
+      const builtIn = context.builtInVariable(expression.identifier);
+      if (builtIn !== undefined) return builtIn;
       return (
         resolveVariableValue(
           context.document,
@@ -76,6 +80,7 @@ export function evaluateVariableExpression(
         context.undeclaredResponseValue(expression.identifier) ??
         null
       );
+    }
     default:
       return assertNever(expression);
   }

package/src/processing-evaluator.ts

@@ -1,4 +1,4 @@
-import type { QtiDocument, QtiProcessingExpression, QtiValue } from "./types.js";
+import type { QtiDiagnostic, 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";
@@ -12,7 +12,8 @@ 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";
+import { numericValueOrNull } from "./processing-values.js";
+import { isRecordValue } from "./value-guards.js";
 
 export interface EvaluationContext {
   document: QtiDocument;
@@ -20,6 +21,9 @@ export interface EvaluationContext {
   outcomes: Record<string, QtiValue>;
   templateValues: Record<string, QtiValue>;
   correctResponses: Record<string, QtiValue>;
+  defaultValues: Record<string, QtiValue>;
+  diagnostics: QtiDiagnostic[];
+  builtInVariable(identifier: string): QtiValue | undefined;
   allowedUndeclaredResponseIdentifiers: ReadonlySet<string>;
   random: () => number;
   customOperators: QtiCustomOperatorRegistry;
@@ -30,6 +34,7 @@ export interface EvaluationContext {
 }
 
 export interface EvaluationOptions {
+  builtInVariable?: ((identifier: string) => QtiValue | undefined) | undefined;
   allowedUndeclaredResponseIdentifiers?: ReadonlySet<string> | readonly string[] | undefined;
 }
 
@@ -53,6 +58,14 @@ export function createEvaluationContext(
     outcomes,
     templateValues,
     correctResponses,
+    defaultValues: {},
+    diagnostics: [],
+    builtInVariable:
+      options.builtInVariable ??
+      ((identifier) =>
+        identifier === "completionStatus"
+          ? (outcomes.completionStatus ?? "not_attempted")
+          : undefined),
     allowedUndeclaredResponseIdentifiers,
     random,
     customOperators,
@@ -105,11 +118,11 @@ export function evaluateProcessingExpression(
     }
     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 "random": {
+      const values = context.evaluate(expression.expression);
+      if (!Array.isArray(values) || values.length === 0) return null;
+      return values[Math.floor(context.random() * values.length)] ?? null;
+    }
     case "isNull":
     case "matchCorrect":
     case "mapResponse":

package/src/processing-expression-children.ts

@@ -3,8 +3,6 @@ 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":
@@ -33,6 +31,8 @@ export function expressionChildren(expression: QtiProcessingExpression): QtiProc
     case "stringMatch":
     case "substring":
       return [expression.left, expression.right];
+    case "isNull":
+    case "random":
     case "not":
     case "round":
     case "roundTo":
@@ -54,7 +54,6 @@ export function expressionChildren(expression: QtiProcessingExpression): QtiProc
     case "baseValue":
     case "correct":
     case "default":
-    case "isNull":
     case "mapResponse":
     case "mapResponsePoint":
     case "matchCorrect":

package/src/processing-expression-tags.ts

@@ -17,6 +17,8 @@ export const identifierExpressionTags = {
 export type IdentifierExpressionType = keyof typeof identifierExpressionTags;
 
 export const unaryExpressionTags = {
+  isNull: "qti-is-null",
+  random: "qti-random",
   containerSize: "qti-container-size",
   round: "qti-round",
   truncate: "qti-truncate",
@@ -47,7 +49,6 @@ export const leftRightExpressionTags = {
   power: "qti-power",
   integerDivide: "qti-integer-divide",
   integerModulus: "qti-integer-modulus",
-  equal: "qti-equal",
 } as const;
 
 export type LeftRightExpressionType = keyof typeof leftRightExpressionTags;