@conform-ed/qti-react 0.0.12 → 0.0.13

package/src/rp/templates.ts

@@ -0,0 +1,190 @@
+/**
+ * The QTI standard response-processing templates as built-in canonical rule trees
+ * (ADR-0004): templates are interpreter inputs, not a separate scoring path. URIs are
+ * matched by their final path segment, so both the QTI 2.x and 3.0 purl forms resolve.
+ */
+
+import type { RpRuleView } from "./types";
+
+const matchCorrectRules: readonly RpRuleView[] = [
+  {
+    kind: "responseCondition",
+    responseIf: {
+      expression: {
+        kind: "match",
+        expressions: [
+          { kind: "variable", identifier: "RESPONSE" },
+          { kind: "correct", identifier: "RESPONSE" },
+        ],
+      },
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "SCORE",
+          expression: { kind: "baseValue", baseType: "float", value: 1 },
+        },
+      ],
+    },
+    responseElse: {
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "SCORE",
+          expression: { kind: "baseValue", baseType: "float", value: 0 },
+        },
+      ],
+    },
+  },
+];
+
+const mapResponseRules: readonly RpRuleView[] = [
+  {
+    kind: "responseCondition",
+    responseIf: {
+      expression: { kind: "isNull", expressions: [{ kind: "variable", identifier: "RESPONSE" }] },
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "SCORE",
+          expression: { kind: "baseValue", baseType: "float", value: 0 },
+        },
+      ],
+    },
+    responseElse: {
+      rules: [
+        { kind: "setOutcomeValue", identifier: "SCORE", expression: { kind: "mapResponse", identifier: "RESPONSE" } },
+      ],
+    },
+  },
+];
+
+const mapResponsePointRules: readonly RpRuleView[] = [
+  {
+    kind: "responseCondition",
+    responseIf: {
+      expression: { kind: "isNull", expressions: [{ kind: "variable", identifier: "RESPONSE" }] },
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "SCORE",
+          expression: { kind: "baseValue", baseType: "float", value: 0 },
+        },
+      ],
+    },
+    responseElse: {
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "SCORE",
+          expression: { kind: "mapResponsePoint", identifier: "RESPONSE" },
+        },
+      ],
+    },
+  },
+];
+
+/**
+ * The Common Cartridge profile templates (CC2_*), transcribed from the published
+ * template XML shipped in CC packages. CC2_match is match_correct under another URI.
+ */
+const cc2MatchBasicRules: readonly RpRuleView[] = [
+  {
+    kind: "responseCondition",
+    responseIf: {
+      expression: {
+        kind: "match",
+        expressions: [
+          { kind: "variable", identifier: "RESPONSE" },
+          { kind: "correct", identifier: "RESPONSE" },
+        ],
+      },
+      rules: [
+        { kind: "setOutcomeValue", identifier: "SCORE", expression: { kind: "variable", identifier: "MAXSCORE" } },
+        {
+          kind: "setOutcomeValue",
+          identifier: "FEEDBACKBASIC",
+          expression: { kind: "baseValue", baseType: "identifier", value: "correct" },
+        },
+      ],
+    },
+    responseElse: {
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "FEEDBACKBASIC",
+          expression: { kind: "baseValue", baseType: "identifier", value: "incorrect" },
+        },
+      ],
+    },
+  },
+];
+
+const cc2MapResponseRules: readonly RpRuleView[] = [
+  {
+    kind: "responseCondition",
+    responseIf: {
+      expression: { kind: "isNull", expressions: [{ kind: "variable", identifier: "RESPONSE" }] },
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "SCORE",
+          expression: { kind: "baseValue", baseType: "float", value: 0 },
+        },
+      ],
+    },
+    responseElse: {
+      rules: [
+        { kind: "setOutcomeValue", identifier: "SCORE", expression: { kind: "mapResponse", identifier: "RESPONSE" } },
+      ],
+    },
+  },
+  {
+    kind: "responseCondition",
+    responseIf: {
+      expression: {
+        kind: "equal",
+        toleranceMode: "exact",
+        expressions: [
+          { kind: "variable", identifier: "MAXSCORE" },
+          { kind: "variable", identifier: "SCORE" },
+        ],
+      },
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "FEEDBACK",
+          expression: { kind: "baseValue", baseType: "identifier", value: "correct" },
+        },
+      ],
+    },
+    responseElse: {
+      rules: [
+        {
+          kind: "setOutcomeValue",
+          identifier: "FEEDBACK",
+          expression: { kind: "baseValue", baseType: "identifier", value: "incorrect" },
+        },
+      ],
+    },
+  },
+];
+
+const templatesBySegment: ReadonlyMap<string, readonly RpRuleView[]> = new Map([
+  ["match_correct", matchCorrectRules],
+  ["map_response", mapResponseRules],
+  ["map_response_point", mapResponsePointRules],
+  ["CC2_match", matchCorrectRules],
+  ["CC2_match_basic", cc2MatchBasicRules],
+  ["CC2_map_response", cc2MapResponseRules],
+]);
+
+/** Resolve a standard-template URI to its canonical rules, or null when unknown. */
+export function resolveTemplate(uri: string): readonly RpRuleView[] | null {
+  const segment =
+    uri
+      .split("/")
+      .at(-1)
+      ?.replace(/\.xml$/u, "") ?? "";
+
+  return templatesBySegment.get(segment) ?? null;
+}

package/src/rp/types.ts

@@ -0,0 +1,161 @@
+/**
+ * Structural views of QTI 3 `responseProcessing` and `outcomeDeclaration` (ADR-0004).
+ * Like the rest of the runtime's views, these are narrowed shapes of the
+ * `@conform-ed/contracts` schemas: validation happens upstream, the interpreter works
+ * against these types and reports anything it does not understand via the Capability
+ * Report instead of guessing.
+ */
+
+import type { CapabilityIssue } from "../capability";
+import type { Cardinality, ResponseDeclarationView, ResponseValue } from "../types";
+
+export type RpScalar = string | number | boolean;
+
+/** An outcome variable's value as exposed to consumers after response processing. */
+export type OutcomeValue = RpScalar | readonly RpScalar[] | null;
+
+/** One named member of a record-cardinality value (QTI record containers). */
+export interface RpRecordField {
+  readonly name: string;
+  readonly baseType?: string;
+  readonly value: RpScalar;
+}
+
+/** The interpreter's typed value model: (baseType, cardinality, members); NULL is null. */
+export interface RpValue {
+  readonly cardinality: Cardinality;
+  readonly baseType?: string;
+  readonly values: readonly RpScalar[];
+  /** Present only when cardinality is "record"; `values` mirrors the field values. */
+  readonly fields?: readonly RpRecordField[];
+}
+
+export type MaybeRpValue = RpValue | null;
+
+export interface OutcomeDeclarationView {
+  readonly identifier: string;
+  readonly cardinality: Cardinality;
+  readonly baseType?: string;
+  readonly defaultValue?: { readonly values: ReadonlyArray<{ readonly value: RpScalar }> };
+}
+
+/**
+ * One expression node. Deliberately loose (`kind: string`): kinds the interpreter
+ * does not implement yet flow through and surface as `unsupported-rp` issues.
+ */
+export interface RpExpressionView {
+  readonly kind: string;
+  readonly identifier?: string;
+  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). */
+  readonly toleranceMode?: "exact" | "absolute" | "relative";
+  readonly tolerance?: ReadonlyArray<number | string>;
+  readonly includeLowerBound?: boolean;
+  readonly includeUpperBound?: boolean;
+  /** 1-based position for `index`. */
+  readonly n?: number | string;
+  /** Function/constant name for `mathOperator`, `mathConstant`, `statsOperator`. */
+  readonly name?: string;
+  /** Rounding controls for `roundTo` and `equalRounded`. */
+  readonly roundingMode?: "decimalPlaces" | "significantFigures";
+  readonly figures?: number | string;
+  /** Pass count for `repeat`. */
+  readonly numberRepeats?: number | 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). */
+  readonly variableIdentifier?: string;
+  readonly weightIdentifier?: string;
+  readonly sectionIdentifier?: string;
+  readonly includeCategory?: string | readonly string[];
+  readonly excludeCategory?: string | readonly string[];
+  /** Vendor identification for `customOperator` (implementation registered by class). */
+  readonly class?: string;
+  readonly definition?: string;
+  /** Named-field selector for `fieldValue` over record-cardinality values. */
+  readonly fieldIdentifier?: string;
+}
+
+/**
+ * A consumer-registered `customOperator` implementation, keyed by its `class`
+ * attribute. Receives the already-evaluated child values; returns NULL-or-value like
+ * any expression. Vendor operators are by definition engine-specific (the spec leaves
+ * them implementation-defined), so nothing ships registered — same opt-in stance as
+ * PCI modules.
+ */
+export type CustomOperatorImplementation = (
+  args: readonly MaybeRpValue[],
+  expression: RpExpressionView,
+) => MaybeRpValue;
+
+export interface RpConditionBranch {
+  readonly expression: RpExpressionView;
+  readonly rules: readonly RpRuleView[];
+}
+
+/** One response rule: responseCondition, setOutcomeValue, or exitResponse. */
+export interface RpRuleView {
+  readonly kind: string;
+  readonly identifier?: string;
+  readonly expression?: RpExpressionView;
+  readonly responseIf?: RpConditionBranch;
+  readonly responseElseIfs?: readonly RpConditionBranch[];
+  readonly responseElse?: { readonly rules: readonly RpRuleView[] };
+}
+
+/** Either a standard-template URI or an explicit rule tree (rules win if both). */
+export interface ResponseProcessingView {
+  readonly template?: string;
+  readonly rules?: readonly RpRuleView[];
+}
+
+/**
+ * Response Normalization (ADR-0004): an opt-in, consumer-configured transform of
+ * candidate string input applied at comparison time. Off by default; always off in
+ * conformance runs. Applied to both sides of string comparisons so keys and candidate
+ * input normalize identically.
+ */
+export type ResponseNormalization = (value: string, declaration?: ResponseDeclarationView) => string;
+
+export interface TemplateDeclarationView {
+  readonly identifier: string;
+  readonly cardinality: Cardinality;
+  readonly baseType?: string;
+  readonly defaultValue?: { readonly values: ReadonlyArray<{ readonly value: RpScalar }> };
+}
+
+export interface ResponseProcessingContext {
+  readonly responseDeclarations: readonly ResponseDeclarationView[];
+  readonly outcomeDeclarations: readonly OutcomeDeclarationView[];
+  readonly responses: Readonly<Record<string, ResponseValue>>;
+  readonly normalization?: ResponseNormalization;
+  /** Template variables for this clone (read by `variable` lookups). */
+  readonly templateDeclarations?: readonly TemplateDeclarationView[];
+  readonly templateValues?: Readonly<Record<string, OutcomeValue>>;
+  /** Adaptive carry-over: outcome values from earlier attempts replace declared defaults. */
+  readonly priorOutcomes?: Readonly<Record<string, OutcomeValue>>;
+  /**
+   * Random source for `random`/`randomInteger`/`randomFloat` in RP (adaptive items,
+   * e.g. Monty Hall door reveals). Seed it from the attempt seed: the seed plus the
+   * submission sequence then replays the exact same outcomes (ADR-0004 determinism).
+   */
+  readonly random?: () => number;
+  /** Registered vendor `customOperator` implementations by class (opt-in). */
+  readonly customOperators?: Readonly<Record<string, CustomOperatorImplementation>>;
+}
+
+export interface ResponseProcessingResult {
+  readonly outcomes: Readonly<Record<string, OutcomeValue>>;
+  /** Non-empty means execution aborted to declared defaults (never partial scoring). */
+  readonly issues: readonly CapabilityIssue[];
+}

package/src/rp/values.ts

@@ -0,0 +1,198 @@
+/**
+ * The interpreter's typed value model. QTI runtime values are (baseType, cardinality,
+ * members); NULL is represented as `null`. Comparison is baseType-aware: pairs are
+ * unordered within the pair, directedPairs ordered, strings normalize through the
+ * consumer's Response Normalization hook (identity by default), numbers compare
+ * numerically.
+ */
+
+import { parsePoint } from "../graphic";
+import { isResponseRecord } from "../types";
+import type { Cardinality, ResponseDeclarationView, ResponseValue } from "../types";
+import type { MaybeRpValue, OutcomeValue, ResponseNormalization, RpScalar, RpValue } from "./types";
+
+export type { MaybeRpValue, RpValue } from "./types";
+
+const numericBaseTypes = new Set(["float", "integer", "duration"]);
+
+export function isNumericBaseType(baseType: string | undefined): boolean {
+  return baseType !== undefined && numericBaseTypes.has(baseType);
+}
+
+/** Coerce a raw scalar to its declared baseType (numbers and booleans may arrive as strings). */
+export function coerceScalar(value: RpScalar, baseType: string | undefined): RpScalar {
+  if (isNumericBaseType(baseType) && typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+
+    if (!Number.isNaN(parsed)) {
+      return parsed;
+    }
+  }
+
+  if (baseType === "boolean" && typeof value === "string") {
+    return value === "true";
+  }
+
+  return value;
+}
+
+/** A record field's base type is carried by its runtime type (no declaration exists). */
+function fieldBaseType(value: string | number | boolean): string {
+  return typeof value === "boolean" ? "boolean" : typeof value === "number" ? "float" : "string";
+}
+
+/** Lift a store ResponseValue into the typed model using its declaration. */
+export function fromResponse(declaration: ResponseDeclarationView, response: ResponseValue): MaybeRpValue {
+  if (response === null) {
+    return null;
+  }
+
+  if (isResponseRecord(response)) {
+    const fields = Object.entries(response).flatMap(([name, member]) =>
+      member === null ? [] : [{ name, baseType: fieldBaseType(member), value: member }],
+    );
+
+    return fields.length === 0 ? null : { cardinality: "record", fields, values: fields.map((field) => field.value) };
+  }
+
+  const raw = typeof response === "string" ? [response] : [...response];
+
+  if (raw.length === 0) {
+    return null;
+  }
+
+  return {
+    cardinality: declaration.cardinality,
+    baseType: declaration.baseType,
+    values: raw.map((value) => coerceScalar(value, declaration.baseType)),
+  };
+}
+
+export function singleNumber(value: MaybeRpValue): number | null {
+  if (value === null || value.values.length !== 1) {
+    return null;
+  }
+
+  const member = value.values[0];
+
+  return typeof member === "number" ? member : null;
+}
+
+export function singleBoolean(value: MaybeRpValue): boolean | null {
+  if (value === null || value.values.length !== 1) {
+    return null;
+  }
+
+  const member = value.values[0];
+
+  return typeof member === "boolean" ? member : null;
+}
+
+export function booleanValue(value: boolean): RpValue {
+  return { cardinality: "single", baseType: "boolean", values: [value] };
+}
+
+export function floatValue(value: number): RpValue {
+  return { cardinality: "single", baseType: "float", values: [value] };
+}
+
+function pairsEqual(a: string, b: string, directed: boolean): boolean {
+  const [a1, a2] = a.trim().split(/\s+/u);
+  const [b1, b2] = b.trim().split(/\s+/u);
+
+  if (a1 === undefined || a2 === undefined || b1 === undefined || b2 === undefined) {
+    return false;
+  }
+
+  if (a1 === b1 && a2 === b2) {
+    return true;
+  }
+
+  return !directed && a1 === b2 && a2 === b1;
+}
+
+export function scalarsEqual(
+  a: RpScalar,
+  b: RpScalar,
+  baseType: string | undefined,
+  normalize?: ResponseNormalization,
+): boolean {
+  if (baseType === "pair" || baseType === "directedPair") {
+    return typeof a === "string" && typeof b === "string" && pairsEqual(a, b, baseType === "directedPair");
+  }
+
+  if (baseType === "point") {
+    if (typeof a !== "string" || typeof b !== "string") {
+      return false;
+    }
+
+    const pointA = parsePoint(a);
+    const pointB = parsePoint(b);
+
+    return pointA !== null && pointB !== null && pointA.x === pointB.x && pointA.y === pointB.y;
+  }
+
+  if (typeof a === "number" || typeof b === "number") {
+    return Number(a) === Number(b);
+  }
+
+  if (normalize && baseType === "string" && typeof a === "string" && typeof b === "string") {
+    return normalize(a) === normalize(b);
+  }
+
+  return a === b;
+}
+
+/** QTI `match`: same cardinality; ordered compares sequences, containers compare multisets. */
+export function valuesMatch(a: RpValue, b: RpValue, normalize?: ResponseNormalization): boolean {
+  const baseType = a.baseType ?? b.baseType;
+
+  if (a.values.length !== b.values.length) {
+    return false;
+  }
+
+  if (a.cardinality === "ordered" || b.cardinality === "ordered") {
+    return a.values.every((value, index) => scalarsEqual(value, b.values[index]!, baseType, normalize));
+  }
+
+  const remaining = [...b.values];
+
+  for (const value of a.values) {
+    const matchIndex = remaining.findIndex((candidate) => scalarsEqual(candidate, value, baseType, normalize));
+
+    if (matchIndex === -1) {
+      return false;
+    }
+
+    remaining.splice(matchIndex, 1);
+  }
+
+  return true;
+}
+
+/** Rebuild a typed value from a flattened OutcomeValue (templates, adaptive carry-over). */
+export function fromFlatValue(value: OutcomeValue, cardinality: Cardinality, baseType?: string): MaybeRpValue {
+  if (value === null) {
+    return null;
+  }
+
+  const values = Array.isArray(value) ? [...value] : [value as RpScalar];
+
+  if (values.length === 0) {
+    return null;
+  }
+
+  return { cardinality, baseType, values: values.map((member) => coerceScalar(member, baseType)) };
+}
+
+export function toOutcomeValue(value: MaybeRpValue): OutcomeValue {
+  if (value === null || value.values.length === 0) {
+    return null;
+  }
+
+  if (value.cardinality === "single") {
+    return value.values[0] ?? null;
+  }
+
+  return value.values;
+}