@longsightgroup/qti3-core 0.10.6 → 0.12.0

package/src/test-xml.ts

@@ -0,0 +1,37 @@
+import { QTI_ASI_NAMESPACE } from "./qti-namespaces.js";
+import type { QtiDiagnostic } from "./types.js";
+import type { XmlNode } from "./xml.js";
+
+/** Report an unsupported construct at its XML source location. */
+export function rejectTestXml(node: XmlNode, diagnostics: QtiDiagnostic[]): void {
+  diagnostics.push({
+    code: "test.xml.unsupported",
+    severity: "error",
+    message: `Unsupported test element or attributes: ${node.localName}.`,
+    source: node.source,
+  });
+}
+
+/** Check the closed test profile's namespace, attributes, children and element-only content. */
+export function checkTestXml(
+  node: XmlNode,
+  names: readonly string[],
+  attrs: readonly string[],
+  diagnostics: QtiDiagnostic[],
+  allowText = false,
+): void {
+  if (
+    node.uri !== QTI_ASI_NAMESPACE ||
+    Object.keys(node.attributes).some(
+      (name) =>
+        name !== "xmlns" &&
+        !name.startsWith("xmlns:") &&
+        !["xsi:schemaLocation", "xml:lang", ...attrs].includes(name),
+    ) ||
+    (!allowText && node.text.trim().length > 0)
+  )
+    rejectTestXml(node, diagnostics);
+  for (const child of node.children)
+    if (child.uri !== QTI_ASI_NAMESPACE || !names.includes(child.localName))
+      rejectTestXml(child, diagnostics);
+}

package/src/trusted-item-session.ts

@@ -1,3 +1,4 @@
+import type { QtiSessionEnvironment } from "./session-builtins.js";
 import { parseQtiXml } from "./parser.js";
 import { itemExpectsAutomatedScore, itemHasExternalScore } from "./item-scoring-expectation.js";
 import { parseQtiResponseVariables } from "./response-validation.js";
@@ -31,6 +32,8 @@ export interface QtiTrustedResponseApplication {
 }
 
 export interface QtiTrustedItemParseOptions {
+  /** Trusted host environment; never take duration/context from candidate response fields. */
+  sessionEnvironment?: QtiSessionEnvironment | undefined;
   allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
 }
 
@@ -48,7 +51,7 @@ export interface RunTrustedItemSessionInput extends QtiTrustedItemParseOptions {
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix;
   submission: QtiTrustedResponseApplication;
   priorState?: QtiAttemptStateV1 | null | undefined;
-  /** Applied before submission. Intended for server-side scoring, not adaptive turns. */
+  /** Applied before submission, except completed is applied after capture. For server scoring, not adaptive turns. */
   attemptStatus?: QtiAttemptStatus | undefined;
   scoring: QtiTrustedItemScoringPolicy;
   requireNumericScore: boolean;
@@ -156,12 +159,15 @@ export function runTrustedItemSession(
     input.diagnosticPrefix,
     input.allowedUndeclaredResponseIdentifiers,
     parsedResult.parsed.diagnostics,
+    input.sessionEnvironment,
   );
   if (!sessionResult.ok) {
     return emptyTrustedItemSessionFailure(sessionResult.diagnostics);
   }
 
-  if (input.attemptStatus) sessionResult.session.setStatus(input.attemptStatus);
+  if (input.attemptStatus && input.attemptStatus !== "completed") {
+    sessionResult.session.setStatus(input.attemptStatus);
+  }
 
   let submission = input.submission;
   if (input.submissionValidation === "strict") {
@@ -189,6 +195,9 @@ export function runTrustedItemSession(
     return emptyTrustedItemSessionFailure(diagnostics);
   }
 
+  // Capture the submitted attempt before closing it, so built-in counters reflect participation.
+  if (input.attemptStatus === "completed") sessionResult.session.setStatus("completed");
+
   const shouldScore = input.scoring === "always" || applicationResult.appliedSubmission;
   const externalScore = itemHasExternalScore(parsedResult.parsed.document.item);
 
@@ -277,11 +286,13 @@ function createTrustedItemSession(
   diagnosticPrefix: QtiTrustedInputDiagnosticPrefix,
   allowedUndeclaredResponseIdentifiers: readonly string[] | undefined,
   existingDiagnostics: QtiDiagnostic[] = [],
+  sessionEnvironment: QtiSessionEnvironment = {},
 ): { ok: true; session: QtiItemSession } | { ok: false; diagnostics: QtiDiagnostic[] } {
   try {
     return {
       ok: true,
       session: createItemSession(parsed.document, priorState ?? undefined, {
+        ...sessionEnvironment,
         allowedUndeclaredResponseIdentifiers,
       }),
     };

package/src/types.ts

@@ -459,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;
 }
 
@@ -593,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 }
@@ -614,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 }
@@ -641,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";
@@ -724,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>;
@@ -744,6 +770,7 @@ export interface QtiScoreResult {
 export type QtiElementSupport =
   | QtiInteractionElementSupport
   | QtiProcessingElementSupport
+  | QtiTestElementSupport
   | QtiItemMetadataElementSupport;
 
 interface QtiElementSupportBase {
@@ -768,6 +795,11 @@ export interface QtiProcessingElementSupport extends QtiElementSupportBase {
   category: "processing";
 }
 
+/** Executable assessment-test support, separate from item processing/rendering. */
+export interface QtiTestElementSupport extends QtiElementSupportBase {
+  category: "test";
+}
+
 export interface QtiItemMetadataElementSupport extends QtiElementSupportBase {
   category: "itemMetadata";
 }

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-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);
+}