@longsightgroup/qti3-core 0.10.5 → 0.11.0

package/src/types.ts

@@ -250,6 +250,8 @@ export interface QtiGapMatchGapSegment {
 }
 
 export interface QtiObjectAsset {
+  /** Attributes of an authored image or picture fallback, when present. */
+  imageAttributes?: Record<string, string> | undefined;
   data?: string | undefined;
   type?: string | undefined;
   width?: string | undefined;
@@ -457,6 +459,13 @@ export interface QtiAssessmentItem {
   stylesheets: QtiStylesheet[];
   body: QtiContentNode[];
   bodyText: string;
+  /** Authored direct children in XML order; omitted for items created without source XML. */
+  sourceChildren?:
+    | readonly {
+        readonly qtiName: string;
+        readonly source?: QtiSourceLocation | undefined;
+      }[]
+    | undefined;
   source?: QtiSourceLocation | undefined;
 }
 
@@ -591,7 +600,7 @@ export type QtiProcessingExpression = (
       baseType?: string | undefined;
     }
   | { type: "null" }
-  | { type: "isNull"; identifier: string }
+  | { type: "isNull"; expression: QtiProcessingExpression }
   | { type: "matchCorrect"; identifier: string; correctIdentifier: string }
   | { type: "match"; left: QtiProcessingExpression; right: QtiProcessingExpression }
   | { type: "correct"; identifier: string }
@@ -612,7 +621,7 @@ export type QtiProcessingExpression = (
       max: number;
       attributes: Record<string, string>;
     }
-  | { type: "random"; values: QtiProcessingExpression[] }
+  | { type: "random"; expression: QtiProcessingExpression }
   | { type: "multiple"; expressions: QtiProcessingExpression[] }
   | { type: "ordered"; expressions: QtiProcessingExpression[] }
   | { type: "index"; expression: QtiProcessingExpression; n: string }
@@ -639,13 +648,18 @@ export type QtiProcessingExpression = (
   | { type: "anyN"; expressions: QtiProcessingExpression[]; min: string; max: string }
   | { type: "or"; expressions: QtiProcessingExpression[] }
   | { type: "not"; expression: QtiProcessingExpression }
-  | { type: "equal"; left: QtiProcessingExpression; right: QtiProcessingExpression }
+  | {
+      type: "equal";
+      left: QtiProcessingExpression;
+      right: QtiProcessingExpression;
+      attributes?: Record<string, string> | undefined;
+    }
   | {
       type: "equalRounded";
       left: QtiProcessingExpression;
       right: QtiProcessingExpression;
       roundingMode: string;
-      figures: number;
+      figures: number | string;
     }
   | {
       type: "numericCompare";
@@ -722,8 +736,22 @@ export interface QtiValidationResult {
   diagnostics: QtiDiagnostic[];
 }
 
+export interface QtiSessionContext {
+  candidateIdentifier: string;
+  testIdentifier: string;
+  environmentIdentifier: string;
+}
+
+export interface QtiBuiltInVariables {
+  numAttempts: number;
+  duration: number | null;
+  attemptInProgress: boolean;
+  context: QtiSessionContext;
+}
+
 export interface QtiAttemptStateV1 {
   schema: "qti3.attempt-state.v1";
+  builtInVariables?: QtiBuiltInVariables | undefined;
   itemIdentifier: string;
   status: QtiAttemptStatus;
   responses: Record<string, QtiValue>;

package/src/validation-declaration-entries.ts

@@ -5,7 +5,7 @@ import {
   isNumericCsv,
   numericCsv,
 } from "./validation-geometry.js";
-import { isFiniteNumber, isInteger } from "./validation-primitives.js";
+import { isBooleanAttribute, isFiniteNumber, isInteger } from "./validation-primitives.js";
 
 interface DeclarationEntryAttributes {
   attributes: Record<string, string>;
@@ -18,6 +18,16 @@ export function validateMapEntryAttributes(
   entry: DeclarationEntryAttributes,
   diagnostics: QtiDiagnostic[],
 ): void {
+  const caseSensitive = entry.attributes["case-sensitive"];
+  if (caseSensitive !== undefined && !isBooleanAttribute(caseSensitive)) {
+    diagnostics.push({
+      code: "mapEntry.caseSensitive",
+      severity: "error",
+      message: `Response declaration ${declarationIdentifier} map entry requires a boolean case-sensitive value.`,
+      path: entry.source?.path,
+      source: entry.source,
+    });
+  }
   if (!entry.attributes["map-key"]) {
     diagnostics.push({
       code: "mapEntry.mapKey.required",

package/src/validation-interactions.ts

@@ -34,10 +34,13 @@ export function validateInteractions(item: QtiAssessmentItem, diagnostics: QtiDi
     validateInteractionSharedVocabulary(interaction, diagnostics);
     validateInteractionChoices(interaction, diagnostics);
     validateInteractionChildren(interaction, diagnostics);
+    validateGraphicGapMatchChildren(interaction, diagnostics);
+    validatePositionObjectChildren(interaction, diagnostics);
     validateInteractionRequiredAttributes(interaction, diagnostics);
     validatePortableCustomInteraction(interaction, item, diagnostics);
     validateInteractionLimitAttributes(interaction, diagnostics);
     validatePatternMaskAttribute(interaction, diagnostics);
+    validateTextInteractionContract(interaction, responseDeclarations, diagnostics);
     validateGraphicHotspotObjectDimensions(interaction, diagnostics);
     validateCorrectResponseReferences(
       interaction,
@@ -649,7 +652,7 @@ function allowedInteractionChildren(interaction: QtiInteraction): Set<string> |
     case "order":
       return setOf(common, ["qti-simple-choice"]);
     case "associate":
-      return setOf(common, ["qti-simple-match-set", "qti-simple-associable-choice"]);
+      return setOf(common, ["qti-simple-associable-choice"]);
     case "match":
       return setOf(common, ["qti-simple-match-set"]);
     case "gapMatch":
@@ -659,22 +662,24 @@ function allowedInteractionChildren(interaction: QtiInteraction): Set<string> |
     case "hottext":
       return setOf(common, staticContentNames());
     case "graphicOrder":
-      return setOf(common, ["object", "qti-hotspot-choice"]);
+      return setOf(common, ["object", "img", "picture", "qti-hotspot-choice"]);
     case "graphicAssociate":
-      return setOf(common, ["object", "qti-associable-hotspot"]);
+      return setOf(common, ["object", "img", "picture", "qti-associable-hotspot"]);
     case "graphicGapMatch":
       return setOf(common, [
         "object",
+        "img",
+        "picture",
         "qti-gap-text",
         "qti-gap-img",
         "qti-associable-hotspot",
-        ...staticContentNames(),
       ]);
     case "hotspot":
-      return setOf(common, ["object", "qti-hotspot-choice"]);
+      return setOf(common, ["object", "img", "picture", "qti-hotspot-choice"]);
     case "positionObject":
-      return setOf(common, ["object", "img", "qti-position-object-stage"]);
+      return new Set(["object", "img", "picture"]);
     case "selectPoint":
+      return setOf(common, ["object", "img", "picture"]);
     case "media":
       return setOf(common, ["audio", "video", "object", "img"]);
     case "drawing":
@@ -722,13 +727,12 @@ function expectedResponseShape(
     return { cardinalities: ["ordered"], baseTypes: ["identifier"] };
   }
   if (interaction.type === "associate" || interaction.type === "graphicAssociate") {
-    return { cardinalities: ["multiple"], baseTypes: ["pair", "directedPair"] };
+    return { cardinalities: ["single", "multiple"], baseTypes: ["pair"] };
   }
-  if (
-    interaction.type === "match" ||
-    interaction.type === "gapMatch" ||
-    interaction.type === "graphicGapMatch"
-  ) {
+  if (interaction.type === "match" || interaction.type === "gapMatch") {
+    return { cardinalities: ["single", "multiple"], baseTypes: ["directedPair"] };
+  }
+  if (interaction.type === "graphicGapMatch") {
     return { cardinalities: ["multiple"], baseTypes: ["directedPair"] };
   }
   if (interaction.type === "selectPoint" || interaction.type === "positionObject") {
@@ -740,8 +744,14 @@ function expectedResponseShape(
   if (interaction.type === "upload") {
     return { cardinalities: ["single"], baseTypes: ["file"] };
   }
-  if (interaction.type === "textEntry" || interaction.type === "extendedText") {
-    return { cardinalities: ["single"], baseTypes: ["string"] };
+  if (interaction.type === "textEntry") {
+    return { cardinalities: ["single", "record"], baseTypes: ["string", "integer", "float"] };
+  }
+  if (interaction.type === "extendedText") {
+    return {
+      cardinalities: ["single", "multiple", "ordered", "record"],
+      baseTypes: ["string", "integer", "float"],
+    };
   }
   if (interaction.type === "drawing") return { cardinalities: ["single"], baseTypes: ["file"] };
   if (interaction.type === "portableCustom") {
@@ -780,3 +790,118 @@ function needsChoices(interaction: QtiInteraction): boolean {
     interaction.type === "hotspot"
   );
 }
+
+function validateTextInteractionContract(
+  interaction: QtiInteraction,
+  declarations: ReadonlyMap<string, QtiResponseDeclaration>,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "textEntry" && interaction.type !== "extendedText") return;
+  const report = (code: string, message: string) =>
+    diagnostics.push({
+      code,
+      severity: "error",
+      message,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  const base = Number(interaction.attributes.base ?? 10);
+  if (!Number.isInteger(base) || base < 2 || base > 36) {
+    report("interaction.text.base", "Text response base must be an integer from 2 through 36.");
+  }
+  const format = interaction.attributes.format;
+  if (
+    format !== undefined &&
+    format !== "plain" &&
+    !(interaction.type === "extendedText" && format === "preformatted") &&
+    !(
+      interaction.type === "extendedText" &&
+      format === "xhtml" &&
+      interaction.responseBaseType === "string"
+    )
+  ) {
+    report(
+      "interaction.text.format.unsupported",
+      `Text format ${format} is not supported; use plain text.`,
+    );
+  }
+  if (interaction.type === "extendedText") {
+    const container =
+      interaction.responseCardinality === "multiple" ||
+      interaction.responseCardinality === "ordered";
+    const max = interaction.attributes["max-strings"];
+    const min = interaction.attributes["min-strings"] ?? "0";
+    if (
+      (container && max === undefined) ||
+      (max !== undefined && !isNonNegativeInteger(max)) ||
+      !isNonNegativeInteger(min) ||
+      Number(min) > (container ? Number(max) : 1)
+    ) {
+      report(
+        "interaction.text.strings",
+        "Extended text requires valid min-strings/max-strings limits; containers require max-strings and the minimum must not exceed the maximum.",
+      );
+    }
+  }
+  const companion = interaction.attributes["string-identifier"];
+  if (companion !== undefined) {
+    const declaration = declarations.get(companion);
+    if (
+      !declaration ||
+      declaration.baseType !== "string" ||
+      declaration.cardinality !== interaction.responseCardinality ||
+      companion === interaction.responseIdentifier ||
+      (interaction.responseBaseType !== "integer" && interaction.responseBaseType !== "float")
+    ) {
+      report(
+        "interaction.text.stringIdentifier",
+        "string-identifier must reference a separate string response with matching cardinality for a numeric text interaction.",
+      );
+    }
+  }
+}
+
+function validateGraphicGapMatchChildren(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "graphicGapMatch") return;
+  const names = interaction.childElements.map((child) => child.qtiName);
+  const sequence = names.join(" ");
+  if (
+    /^(?:qti-prompt )?(?:object|img|picture)(?: qti-gap-(?:text|img))+(?: qti-associable-hotspot)+$/.test(
+      sequence,
+    )
+  )
+    return;
+  diagnostics.push({
+    code: "interaction.graphicGapMatch.children",
+    severity: "error",
+    message:
+      "Graphic Gap Match requires an optional prompt, one image, gap choices, then one or more associable hotspots, in that order.",
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}
+
+function validatePositionObjectChildren(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "positionObject") return;
+  const [child] = interaction.childElements;
+  if (
+    interaction.childElements.length === 1 &&
+    child &&
+    ["object", "img", "picture"].includes(child.qtiName)
+  )
+    return;
+  diagnostics.push({
+    code: "interaction.positionObject.children",
+    severity: "error",
+    message:
+      "Position Object requires exactly one marker image (object, img, or picture); instructions belong before its stage.",
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}

package/src/validation-item-children.ts

@@ -0,0 +1,48 @@
+import type { QtiAssessmentItem, QtiDiagnostic } from "./types.js";
+
+// QTI 3.0.1 AssessmentItemDType sequence:
+// https://purl.imsglobal.org/spec/qti/v3p0/schema/xsd/imsqti_itemv3p0p1_v1p0.xsd
+const itemChildOrder: readonly string[] = [
+  "qti-context-declaration",
+  "qti-response-declaration",
+  "qti-outcome-declaration",
+  "qti-template-declaration",
+  "qti-template-processing",
+  "qti-assessment-stimulus-ref",
+  "qti-companion-materials-info",
+  "qti-stylesheet",
+  "qti-item-body",
+  "qti-catalog-info",
+  "qti-response-processing",
+  "qti-modal-feedback",
+];
+
+/** Validate the authored direct-child sequence retained by the XML parser. */
+export function validateAssessmentItemChildren(
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  let lastOrder = -1;
+  for (const child of item.sourceChildren ?? []) {
+    const order = itemChildOrder.indexOf(child.qtiName);
+    if (order < 0) {
+      diagnostics.push({
+        code: "assessmentItem.child.unsupported",
+        severity: "error",
+        message: `qti-assessment-item does not allow ${child.qtiName} as a direct child.`,
+        path: child.source?.path,
+        source: child.source,
+      });
+    } else if (order < lastOrder) {
+      diagnostics.push({
+        code: "assessmentItem.child.order",
+        severity: "error",
+        message: `${child.qtiName} appears out of QTI 3 qti-assessment-item child order.`,
+        path: child.source?.path,
+        source: child.source,
+      });
+    } else {
+      lastOrder = order;
+    }
+  }
+}

package/src/validation-processing.ts

@@ -7,6 +7,7 @@ import type {
   QtiSetOutcomeValue,
   QtiTemplateRule,
 } from "./types.js";
+import { parseXmlSchemaRegex, patternVariableIdentifier } from "./xml-schema-regex.js";
 import { expressionChildren } from "./processing-expression-children.js";
 import { MAX_QTI_REPEAT_RESULT_ELEMENTS } from "./processing-limits.js";
 import { MATH_OPERATOR_NAMES, STATS_OPERATOR_NAMES } from "./processing-operators.js";
@@ -21,6 +22,7 @@ import {
   isInteger,
 } from "./validation-primitives.js";
 import { COMPLETION_STATUS } from "./attempt-state-constants.js";
+import { validateEqualTolerance } from "./processing-equality.js";
 
 export function validateResponseProcessingTemplate(
   item: QtiAssessmentItem,
@@ -120,7 +122,14 @@ export function validateProcessingReferences(
   const outcomes = new Set(item.outcomeDeclarations.map((declaration) => declaration.identifier));
   outcomes.add(COMPLETION_STATUS);
   const templates = new Set(item.templateDeclarations.map((declaration) => declaration.identifier));
-  const variables = new Set([...responses, ...outcomes, ...templates]);
+  const variables = new Set([
+    ...responses,
+    ...outcomes,
+    ...templates,
+    "numAttempts",
+    "QTI_CONTEXT",
+    ...(item.timeDependent ? ["duration"] : []),
+  ]);
 
   for (const rule of item.templateProcessing?.rules ?? []) {
     validateTemplateRule(rule, responses, outcomes, templates, variables, diagnostics);
@@ -324,7 +333,7 @@ function validateExpressionReferences(
 ): void {
   if (!expression) return;
 
-  if (expression.type === "variable" || expression.type === "isNull") {
+  if (expression.type === "variable") {
     validateProcessingIdentifier(
       expression.identifier,
       "processing.variable",
@@ -429,6 +438,30 @@ function validateExpressionReferences(
     }
   }
 
+  if (expression.type === "patternMatch") {
+    const reference = patternVariableIdentifier(expression.pattern);
+    if (reference !== undefined) {
+      if (!variables.has(reference))
+        diagnostics.push({
+          code: "processing.variable.reference",
+          severity: "error",
+          message: `Pattern references missing variable ${reference}.`,
+          source: expression.source,
+          path: expression.source?.path,
+        });
+    } else {
+      const parsed = parseXmlSchemaRegex(expression.pattern);
+      if (!parsed.ok)
+        diagnostics.push({
+          code: `processing.pattern.${parsed.problem.code}`,
+          severity: "error",
+          message: parsed.problem.message,
+          source: expression.source,
+          path: expression.source?.path,
+        });
+    }
+  }
+
   if (expression.type === "randomInteger") {
     validateRandomIntegerExpression(expression, diagnostics);
   }
@@ -446,11 +479,16 @@ function validateExpressionReferences(
       "qti-equal-rounded",
       expression.roundingMode,
       expression.figures,
+      variables,
       diagnostics,
       expression.source,
     );
   }
 
+  if (expression.type === "equal") {
+    validateEqualTolerance(expression, variables, diagnostics);
+  }
+
   if (expression.type === "anyN") {
     validateAnyNBound("min", expression.min, responses, variables, diagnostics, expression.source);
     validateAnyNBound("max", expression.max, responses, variables, diagnostics, expression.source);
@@ -544,7 +582,8 @@ const statsOperatorNames = new Set<string>(STATS_OPERATOR_NAMES);
 function validateRounding(
   qtiName: string,
   roundingMode: string,
-  figures: number,
+  figures: number | string,
+  variables: ReadonlySet<string>,
   diagnostics: QtiDiagnostic[],
   source: QtiDiagnostic["source"],
 ): void {
@@ -558,7 +597,10 @@ function validateRounding(
     });
   }
   const validFigures =
-    Number.isInteger(figures) && (roundingMode === "decimalPlaces" ? figures >= 0 : figures > 0);
+    typeof figures === "string"
+      ? variables.has(figures)
+      : Number.isInteger(figures) &&
+        (roundingMode === "decimalPlaces" ? figures >= 0 : figures > 0);
   if (!validFigures) {
     diagnostics.push({
       code: "processing.roundingFigures",
@@ -683,12 +725,7 @@ function minimumExpressionElements(expression: QtiProcessingExpression): number
     return minimumProducedElements(expression.expressions);
   }
   if (expression.type === "random") {
-    if (expression.values.length === 0) return 0;
-    let minimum = MAX_QTI_REPEAT_RESULT_ELEMENTS + 1;
-    for (const value of expression.values) {
-      minimum = Math.min(minimum, minimumExpressionElements(value));
-    }
-    return minimum;
+    return minimumExpressionElements(expression.expression) > 0 ? 1 : 0;
   }
   if (expression.type !== "repeat" || !/^\d+$/.test(expression.numberRepeats)) return 0;
   const perRepeat = minimumProducedElements(expression.expressions);

package/src/validation.ts

@@ -1,3 +1,4 @@
+import { validateAssessmentItemChildren } from "./validation-item-children.js";
 import type {
   QtiAssessmentItem,
   QtiBaseType,
@@ -44,6 +45,7 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
 
   requireIdentifier("qti-assessment-item", item.identifier, diagnostics, item.source);
   validateAssessmentItemRoot(item, diagnostics);
+  validateAssessmentItemChildren(item, diagnostics);
   validateItemBody(item, diagnostics);
   validateItemBodySharedVocabulary(item, diagnostics);
   validateDeclarationIdentifiers(item, diagnostics);
@@ -132,6 +134,18 @@ function validateDeclarationIdentifiers(
         source: declaration.source,
       });
     }
+    if (
+      ["numAttempts", "duration", "QTI_CONTEXT"].includes(declaration.identifier) ||
+      (declaration.identifier === COMPLETION_STATUS && declaration.kind !== "outcome")
+    ) {
+      diagnostics.push({
+        code: "declaration.builtIn",
+        severity: "error",
+        message: `${declaration.identifier} is a reserved built-in variable and must not be declared explicitly.`,
+        path: declaration.source?.path,
+        source: declaration.source,
+      });
+    }
     if (seen.has(declaration.identifier)) {
       diagnostics.push({
         code: "identifier.duplicate",

package/src/value-guards.ts

@@ -0,0 +1,6 @@
+import type { QtiRecordValue, QtiValue } from "./types.js";
+
+/** Narrow an already-typed QTI value to its record variant. */
+export function isRecordValue(value: QtiValue): value is QtiRecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}