@conform-ed/qti-react 0.0.14 → 0.0.16

package/src/rp/interpreter.ts

@@ -14,6 +14,7 @@ import {
   evaluateExpression,
   type EvalEnv,
 } from "./evaluate";
+import { hasLookupTable, lookupTableValue } from "./lookup-table";
 import { resolveTemplate } from "./templates";
 import type {
   OutcomeDeclarationView,
@@ -35,7 +36,13 @@ import {
   type MaybeRpValue,
 } from "./values";
 
-const supportedRuleKinds = new Set(["responseCondition", "setOutcomeValue", "exitResponse"]);
+const supportedRuleKinds = new Set([
+  "responseCondition",
+  "setOutcomeValue",
+  "lookupOutcomeValue",
+  "responseProcessingFragment",
+  "exitResponse",
+]);
 
 /**
  * RP additionally supports the random operators: the attempt store always provides a
@@ -83,6 +90,13 @@ export function executeResponseProcessing(
   function initialOutcomes(): Map<string, MaybeRpValue> {
     const outcomes = defaultOutcomes(context.outcomeDeclarations);
 
+    // The built-in completionStatus is "declared implicitly" and starts at
+    // "not_attempted" (§2.2.2.3); seeding it into the map lets setOutcomeValue
+    // change it. Explicit declarations (legacy content) keep the declared path.
+    if (!outcomes.has("completionStatus")) {
+      outcomes.set("completionStatus", rpValue("single", [context.completionStatus ?? "not_attempted"], "identifier"));
+    }
+
     // Adaptive carry-over: prior outcome values (from earlier attempts in the same
     // item session) replace the declared defaults.
     for (const [identifier, prior] of Object.entries(context.priorOutcomes ?? {})) {
@@ -110,6 +124,16 @@ export function executeResponseProcessing(
 
   const env: EvalEnv = {
     lookupVariable: (identifier) => {
+      // Built-in session variables (reserved identifiers; items must not declare
+      // them): duration in seconds, numAttempts including the current attempt.
+      if (identifier === "duration") {
+        return context.duration === undefined ? null : rpValue("single", [context.duration], "duration");
+      }
+
+      if (identifier === "numAttempts") {
+        return context.numAttempts === undefined ? null : rpValue("single", [context.numAttempts], "integer");
+      }
+
       const declaration = declarationsById.get(identifier);
 
       if (declaration) {
@@ -130,6 +154,22 @@ export function executeResponseProcessing(
     },
     responseDeclaration: (identifier) => declarationsById.get(identifier),
     responseValue: (identifier) => context.responses[identifier] ?? null,
+    variableDefault: (identifier) => {
+      const declaration =
+        declarationsById.get(identifier) ??
+        context.outcomeDeclarations.find((entry) => entry.identifier === identifier) ??
+        templateDeclarationsById.get(identifier);
+
+      if (!declaration?.defaultValue) {
+        return null; // "NULL if no default value was declared" (§2.11.1.3)
+      }
+
+      return rpValue(
+        declaration.cardinality,
+        declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
+        declaration.baseType,
+      );
+    },
     normalization: context.normalization,
     random: context.random,
     customOperators: context.customOperators,
@@ -162,6 +202,28 @@ export function executeResponseProcessing(
         continue;
       }
 
+      // "A simple group of responseRules" (§5.118): executes inline, in order, over
+      // the same outcome state; exitResponse propagates through the recursion.
+      if (rule.kind === "responseProcessingFragment") {
+        executeRules(rule.rules ?? []);
+        continue;
+      }
+
+      if (rule.kind === "lookupOutcomeValue") {
+        if (rule.identifier !== undefined && rule.expression !== undefined) {
+          const declaration = context.outcomeDeclarations.find((entry) => entry.identifier === rule.identifier);
+
+          if (!hasLookupTable(declaration)) {
+            // §5.87 presumes "the lookupTable associated with the outcome's
+            // declaration" — no table, no spec-defined value: refuse, never guess.
+            throw new RpUnsupportedError("lookupOutcomeValue");
+          }
+
+          outcomes.set(rule.identifier, lookupTableValue(declaration, evaluateExpression(rule.expression, env)));
+        }
+        continue;
+      }
+
       // responseCondition
       if (rule.responseIf && branchTaken(rule.responseIf)) {
         continue;
@@ -195,6 +257,12 @@ export function executeResponseProcessing(
 export interface RpIssueOptions {
   /** `customOperator` classes the consumer has registered implementations for. */
   readonly customOperatorClasses?: ReadonlySet<string>;
+  /**
+   * The item's outcome declarations; when supplied, a `lookupOutcomeValue` rule whose
+   * declaration carries no lookupTable is reported statically (gate parity with the
+   * runtime refusal).
+   */
+  readonly outcomeDeclarations?: readonly OutcomeDeclarationView[];
 }
 
 /** Static coverage walk for `canDeliver`: reports constructs the interpreter lacks without executing. */
@@ -223,10 +291,22 @@ export function collectRpIssues(
         continue;
       }
 
+      if (rule.kind === "lookupOutcomeValue" && options?.outcomeDeclarations !== undefined) {
+        const declaration = options.outcomeDeclarations.find((entry) => entry.identifier === rule.identifier);
+
+        if (!hasLookupTable(declaration)) {
+          report("lookupOutcomeValue", "Outcome declaration has no matchTable/interpolationTable.");
+        }
+      }
+
       if (rule.expression) {
         collectExpressionIssues(rule.expression, rpExpressionKinds, report, options?.customOperatorClasses);
       }
 
+      if (rule.rules) {
+        walkRules(rule.rules); // responseProcessingFragment nesting (§5.118)
+      }
+
       for (const branch of [rule.responseIf, ...(rule.responseElseIfs ?? [])]) {
         if (branch) {
           collectExpressionIssues(branch.expression, rpExpressionKinds, report, options?.customOperatorClasses);

package/src/rp/lookup-table.ts

@@ -0,0 +1,46 @@
+/**
+ * lookupTable evaluation for the `lookupOutcomeValue` rule (§5.87): "sets the value
+ * of an outcome variable to the value obtained by looking up the value of the
+ * associated expression in the lookupTable associated with the outcome's
+ * declaration." Shared by the item interpreter and the test controller — the test's
+ * own outcome declarations use the same view type.
+ */
+
+import type { OutcomeDeclarationView } from "./types";
+import { coerceScalar, rpValue, singleNumber, type MaybeRpValue } from "./values";
+
+export function hasLookupTable(declaration: OutcomeDeclarationView | undefined): declaration is OutcomeDeclarationView {
+  return declaration?.matchTable !== undefined || declaration?.interpolationTable !== undefined;
+}
+
+/**
+ * Look `source` up in the declaration's lookupTable. A NULL or non-numeric source is
+ * read as "no matching table entry is found" (§5.90.1) — an interpretive call the
+ * spec leaves open — so it takes the defaultValue path, never a refusal. "If
+ * omitted, the NULL value is used." (§5.90.1/§5.78.1)
+ */
+export function lookupTableValue(declaration: OutcomeDeclarationView, source: MaybeRpValue): MaybeRpValue {
+  const value = singleNumber(source);
+  const table = declaration.matchTable ?? declaration.interpolationTable;
+  const target = value === null ? undefined : matchedTarget(declaration, value);
+  const result = target ?? table?.defaultValue;
+
+  if (result === undefined) {
+    return null;
+  }
+
+  return rpValue("single", [coerceScalar(result, declaration.baseType)], declaration.baseType);
+}
+
+function matchedTarget(declaration: OutcomeDeclarationView, value: number) {
+  if (declaration.matchTable) {
+    // "the first qti-match-table-entry with an exact match to the source" (§5.90)
+    return declaration.matchTable.matchTableEntries.find((entry) => entry.sourceValue === value)?.targetValue;
+  }
+
+  // "the first interpolationTableEntry with a sourceValue that is less than or equal
+  // to (subject to includeBoundary) the source value" (§5.78); document order decides.
+  return declaration.interpolationTable?.interpolationTableEntries.find((entry) =>
+    (entry.includeBoundary ?? true) ? entry.sourceValue <= value : entry.sourceValue < value,
+  )?.targetValue;
+}

package/src/rp/template-processing.ts

@@ -118,6 +118,19 @@ export function executeTemplateProcessing(
     lookupVariable: (identifier) => templateValues.get(identifier) ?? null,
     responseDeclaration: (identifier) => responseDeclarationsById.get(identifier),
     responseValue: () => null, // no candidate responses exist at template-processing time
+    variableDefault: (identifier) => {
+      const declaration = declarationsById.get(identifier) ?? responseDeclarationsById.get(identifier);
+
+      if (!declaration?.defaultValue) {
+        return null; // "NULL if no default value was declared" (§2.11.1.3)
+      }
+
+      return rpValue(
+        declaration.cardinality,
+        declaration.defaultValue.values.map((entry) => coerceScalar(entry.value, declaration.baseType)),
+        declaration.baseType,
+      );
+    },
     random: mulberry32(context.seed),
     customOperators: context.customOperators,
   };
@@ -229,6 +242,34 @@ export function executeTemplateProcessing(
   };
 }
 
+/**
+ * The effective template declarations for a clone: test-level `templateDefault`
+ * values (§5.152) replace the declared defaults. A NULL value clears the default.
+ */
+export function applyTemplateDefaultOverrides(
+  declarations: readonly TemplateDeclarationView[],
+  overrides: Readonly<Record<string, OutcomeValue>>,
+): readonly TemplateDeclarationView[] {
+  return declarations.map((declaration) => {
+    if (!(declaration.identifier in overrides)) {
+      return declaration;
+    }
+
+    const value = overrides[declaration.identifier];
+
+    if (value === null || value === undefined) {
+      const { defaultValue: _cleared, ...rest } = declaration;
+
+      return rest;
+    }
+
+    return {
+      ...declaration,
+      defaultValue: { values: (Array.isArray(value) ? value : [value]).map((member) => ({ value: member })) },
+    };
+  });
+}
+
 /** The effective response declarations for a clone: setCorrectResponse overrides applied. */
 export function applyCorrectResponseOverrides(
   declarations: readonly ResponseDeclarationView[],

package/src/rp/types.ts

@@ -32,11 +32,53 @@ export interface RpValue {
 
 export type MaybeRpValue = RpValue | null;
 
+/** One matchTable row: exact integer source → target (§7.23). */
+export interface MatchTableEntryView {
+  readonly sourceValue: number;
+  readonly targetValue: RpScalar;
+}
+
+/**
+ * "A matchTable transforms a source integer by finding the first
+ * qti-match-table-entry with an exact match to the source." (§5.90)
+ */
+export interface MatchTableView {
+  /** "The default outcome value to be used when no matching table entry is found.
+   * If omitted, the NULL value is used." (§5.90.1) */
+  readonly defaultValue?: RpScalar;
+  readonly matchTableEntries: readonly MatchTableEntryView[];
+}
+
+/** One interpolationTable row; sourceValue is "the lower bound … to match this entry" (§7.18.1). */
+export interface InterpolationTableEntryView {
+  readonly sourceValue: number;
+  readonly targetValue: RpScalar;
+  /** "If 'true', the default, then an exact match of the value is considered a match
+   * of this entry." (§7.18.2) */
+  readonly includeBoundary?: boolean;
+}
+
+/**
+ * "An interpolationTable transforms a source float (or integer) by finding the first
+ * interpolationTableEntry with a sourceValue that is less than or equal to (subject
+ * to includeBoundary) the source value." (§5.78)
+ */
+export interface InterpolationTableView {
+  readonly defaultValue?: RpScalar;
+  readonly interpolationTableEntries: readonly InterpolationTableEntryView[];
+}
+
 export interface OutcomeDeclarationView {
   readonly identifier: string;
   readonly cardinality: Cardinality;
   readonly baseType?: string;
   readonly defaultValue?: { readonly values: ReadonlyArray<{ readonly value: RpScalar }> };
+  /** The declaration's lookupTable (at most one of the two), read by `lookupOutcomeValue` (§5.87). */
+  readonly matchTable?: MatchTableView;
+  readonly interpolationTable?: InterpolationTableView;
+  /** Declared score bounds, aggregated by `outcomeMaximum`/`outcomeMinimum` (§2.11.2.6-7). */
+  readonly normalMaximum?: number;
+  readonly normalMinimum?: number;
 }
 
 /**
@@ -49,11 +91,14 @@ export interface RpExpressionView {
   readonly baseType?: string;
   readonly value?: RpScalar;
   readonly expressions?: readonly RpExpressionView[];
-  /** Bounds/step for the random operators (template processing). */
-  readonly min?: number;
-  readonly max?: number;
-  readonly step?: number;
-  /** `equal` tolerance window; string entries are template references (unsupported). */
+  /**
+   * Bounds/step for the random operators and `anyN`; string values are variable
+   * references resolved at runtime (§2.11.3.6), bare or brace-enclosed (§7.13).
+   */
+  readonly min?: number | string;
+  readonly max?: number | string;
+  readonly step?: number | string;
+  /** `equal` tolerance window; string entries are variable references. */
   readonly toleranceMode?: "exact" | "absolute" | "relative";
   readonly tolerance?: ReadonlyArray<number | string>;
   readonly includeLowerBound?: boolean;
@@ -67,14 +112,18 @@ export interface RpExpressionView {
   readonly figures?: number | string;
   /** Pass count for `repeat`. */
   readonly numberRepeats?: number | string;
+  /** XSD-dialect pattern for `patternMatch`; "{ref}" resolves from a variable (§7.13). */
+  readonly pattern?: string;
   /** String comparison controls for `stringMatch` and `substring`. */
   readonly caseSensitive?: boolean;
   readonly substring?: boolean;
   /** Area for `inside` (QTI shape + coords string). */
   readonly shape?: string;
   readonly coords?: string;
-  /** Test-level subset selection (`testVariables` and the `number*` aggregates). */
+  /** Test-level subset selection (`testVariables`, `outcomeMinimum`/`outcomeMaximum`, `number*`). */
   readonly variableIdentifier?: string;
+  /** Outcome variable whose declared bounds `outcomeMinimum`/`outcomeMaximum` look up (§7.28.4). */
+  readonly outcomeIdentifier?: string;
   readonly weightIdentifier?: string;
   readonly sectionIdentifier?: string;
   readonly includeCategory?: string | readonly string[];
@@ -103,11 +152,16 @@ export interface RpConditionBranch {
   readonly rules: readonly RpRuleView[];
 }
 
-/** One response rule: responseCondition, setOutcomeValue, or exitResponse. */
+/**
+ * One response rule: responseCondition, setOutcomeValue, lookupOutcomeValue,
+ * responseProcessingFragment, or exitResponse.
+ */
 export interface RpRuleView {
   readonly kind: string;
   readonly identifier?: string;
   readonly expression?: RpExpressionView;
+  /** Nested rules of a `responseProcessingFragment` (§5.118). */
+  readonly rules?: readonly RpRuleView[];
   readonly responseIf?: RpConditionBranch;
   readonly responseElseIfs?: readonly RpConditionBranch[];
   readonly responseElse?: { readonly rules: readonly RpRuleView[] };
@@ -156,6 +210,20 @@ export interface ResponseProcessingContext {
    * submission sequence then replays the exact same outcomes (ADR-0004 determinism).
    */
   readonly random?: (() => number) | undefined;
+  /**
+   * Built-in session variables (reserved identifiers; items must not declare them).
+   * `duration` is the item session's elapsed seconds; `numAttempts` "increases by 1
+   * at the start of each attempt", so it includes the attempt being scored.
+   */
+  readonly duration?: number | undefined;
+  readonly numAttempts?: number | undefined;
+  /**
+   * The session's current `completionStatus` — the third built-in, "declared
+   * implicitly"; it enters the outcome map (defaulting to "not_attempted") so
+   * `setOutcomeValue` can change it (§2.2.2.3). An explicit declaration (legacy
+   * content) wins over this value.
+   */
+  readonly completionStatus?: string | undefined;
   /** Registered vendor `customOperator` implementations by class (opt-in). */
   readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>> | undefined;
 }