@longsightgroup/qti3-core 0.11.0 → 0.12.1

package/src/test-session.ts

@@ -0,0 +1,160 @@
+import {
+  evaluateTestExpression,
+  processTestOutcomes,
+  type QtiTestSubmission,
+} from "./test-processing.js";
+import {
+  testFailure,
+  type QtiExecutableTest,
+  type QtiTestItemRef,
+  type QtiTestResult,
+} from "./test-model.js";
+import type { QtiValue } from "./types.js";
+
+interface TestSessionBase {
+  readonly testIdentifier: string;
+  readonly submissions: readonly QtiTestSubmission[];
+  readonly outcomes: Readonly<Record<string, QtiValue>>;
+}
+
+/** Live route state. Only an active session has a current item. */
+export type QtiTestSession = TestSessionBase &
+  (
+    | { readonly status: "active"; readonly currentItemRef: string }
+    | { readonly status: "completed" }
+  );
+
+/** Stable JSON contract: computed frontier/outcomes are reconstructed, never trusted. */
+export interface QtiTestSessionSnapshot {
+  readonly version: 1;
+  readonly testIdentifier: string;
+  readonly submissions: readonly QtiTestSubmission[];
+}
+
+/** Start a validated test at its first item. */
+export function startQtiTest(test: QtiExecutableTest): QtiTestSession {
+  const first = test.sections[0].items[0];
+  return {
+    status: "active",
+    testIdentifier: test.identifier,
+    currentItemRef: first.identifier,
+    submissions: [],
+    outcomes: processTestOutcomes(test, []).outcomes,
+  };
+}
+
+/** Accept one trusted scored answer at the frontier; does not mutate input state. */
+export function submitQtiTestAnswer(
+  test: QtiExecutableTest,
+  session: QtiTestSession,
+  submission: QtiTestSubmission,
+): QtiTestResult<QtiTestSession> {
+  if (session.testIdentifier !== test.identifier)
+    return testFailure("session.test", "Session belongs to another test.");
+  if (session.status !== "active" || session.currentItemRef !== submission.itemRef)
+    return testFailure("session.frontier", "Only the current unanswered item can be submitted.");
+  if (!Number.isFinite(submission.score))
+    return testFailure("session.score", "Item score must be a finite number.");
+  const sectionIndex = test.sections.findIndex((s) =>
+    s.items.some((i) => i.identifier === submission.itemRef),
+  );
+  const section = test.sections[sectionIndex];
+  if (!section) return testFailure("session.item", "Current item does not belong to the test.");
+  const submissions = [
+    ...session.submissions,
+    { itemRef: submission.itemRef, score: submission.score },
+  ];
+  const { outcomes } = processTestOutcomes(test, submissions);
+  const base = { testIdentifier: test.identifier, submissions, outcomes };
+  const next = nextItemAfter(
+    test,
+    sectionIndex,
+    submission.itemRef,
+    (expression) =>
+      evaluateTestExpression(expression, {
+        outcomes,
+        submissions,
+        categories: new Map(
+          test.sections.flatMap((candidate) =>
+            candidate.items.map((item) => [item.identifier, item.categories] as const),
+          ),
+        ),
+      }) === true,
+  );
+  return {
+    ok: true,
+    value: next
+      ? { ...base, status: "active", currentItemRef: next.identifier }
+      : { ...base, status: "completed" },
+  };
+}
+
+function nextItemAfter(
+  test: QtiExecutableTest,
+  sectionIndex: number,
+  itemRef: string,
+  evaluate: (expression: import("./test-expression.js").QtiTestExpression) => boolean,
+): QtiTestItemRef | undefined {
+  const section = test.sections[sectionIndex];
+  if (!section) return undefined;
+  const nextItem =
+    section.items[section.items.findIndex((item) => item.identifier === itemRef) + 1];
+  if (nextItem) return nextItem;
+  const branch = section.branches.find((candidate) => evaluate(candidate.expression));
+  if (branch?.target === "EXIT_TEST") return undefined;
+  const nextSection = branch
+    ? test.sections.find((candidate) => candidate.identifier === branch.target)
+    : test.sections[sectionIndex + 1];
+  return nextSection?.items[0];
+}
+
+/** Project session state into its minimal persisted contract. */
+export function snapshotQtiTestSession(session: QtiTestSession): QtiTestSessionSnapshot {
+  return {
+    version: 1,
+    testIdentifier: session.testIdentifier,
+    submissions: session.submissions.map((s) => ({ itemRef: s.itemRef, score: s.score })),
+  };
+}
+
+/** Parse persisted state and replay it against the pinned test to reject impossible routes. */
+export function restoreQtiTestSession(
+  test: QtiExecutableTest,
+  input: unknown,
+): QtiTestResult<QtiTestSession> {
+  if (
+    typeof input !== "object" ||
+    input === null ||
+    !("version" in input) ||
+    input.version !== 1 ||
+    !("testIdentifier" in input) ||
+    input.testIdentifier !== test.identifier ||
+    !("submissions" in input) ||
+    !Array.isArray(input.submissions) ||
+    Object.keys(input).some((k) => !["version", "testIdentifier", "submissions"].includes(k))
+  )
+    return testFailure("session.snapshot", "Invalid test session snapshot.");
+  if (input.submissions.length > test.sections.reduce((n, s) => n + s.items.length, 0))
+    return testFailure("session.length", "Session exceeds test inventory.");
+  let session = startQtiTest(test);
+  for (const raw of input.submissions) {
+    const value: unknown = raw;
+    if (
+      typeof value !== "object" ||
+      value === null ||
+      !("itemRef" in value) ||
+      typeof value.itemRef !== "string" ||
+      !("score" in value) ||
+      typeof value.score !== "number" ||
+      Object.keys(value).some((k) => k !== "itemRef" && k !== "score")
+    )
+      return testFailure("session.submission", "Invalid saved test submission.");
+    const result = submitQtiTestAnswer(test, session, {
+      itemRef: value.itemRef,
+      score: value.score,
+    });
+    if (!result.ok) return result;
+    session = result.value;
+  }
+  return { ok: true, value: session };
+}

package/src/test-support.ts

@@ -0,0 +1,31 @@
+import { testExpressionSyntax } from "./test-expression.js";
+import type { QtiTestElementSupport } from "./types.js";
+
+/** Explicit scope and evidence for the finite forward-branching execution profile. */
+export const testExecutionSupport: readonly QtiTestElementSupport[] = [
+  "qti-assessment-test",
+  "qti-test-part",
+  "qti-assessment-section",
+  "qti-assessment-item-ref",
+  "qti-branch-rule",
+  "qti-outcome-processing",
+  "qti-test-variables",
+].map((qtiName) => ({
+  qtiName,
+  category: "test",
+  support: "supported",
+  specReference: "QTI 3.0.1 ASI test sequencing and outcome processing",
+  parse: true,
+  validate: true,
+  render: false,
+  process: true,
+  fixtures: ["tests/fixtures/staged-assessment-test.xml"],
+  tests: [
+    "packages/core/src/test-session.test.ts",
+    "packages/core/src/test-validation.test.ts",
+    "packages/core/src/test-language.test.ts",
+    "packages/writer/src/assessment-test.test.ts",
+    "packages/conformance/src/staged-assessment.test.ts",
+  ],
+  notes: `parseQtiTest / startQtiTest / submitQtiTestAnswer only: one linear, individually submitted part; flat fixed sections; forward section branches and EXIT_TEST; scalar test outcomes, SCORE aggregation by one category, expressions: ${testExpressionSyntax.map((entry) => entry.name).join(", ")}. Unsupported test features are rejected. Not item-player or general test-runner certification.`,
+}));

package/src/test-validation.ts

@@ -0,0 +1,190 @@
+import { assertNever } from "./assert-never.js";
+import type { QtiTestExpression } from "./test-expression.js";
+import { isQtiIdentifier } from "./qti-identifier.js";
+import { isQtiPackageItemHref } from "./qti-package-paths.js";
+import { isTestBaseType } from "./test-expression.js";
+import { checkTestExpression, isBoolean, isTestScalarValue } from "./test-expression-validation.js";
+import type { QtiDiagnostic } from "./types.js";
+import type { QtiExecutableTest, QtiTestDefinition, QtiTestResult } from "./test-model.js";
+
+type Reject = (code: string, message: string) => void;
+
+/** Establish executable support for the finite, flat-section QTI test profile. */
+export function validateQtiTest(test: QtiTestDefinition): QtiTestResult<QtiExecutableTest> {
+  const diagnostics: QtiDiagnostic[] = [];
+  const reject: Reject = (code, message) => {
+    diagnostics.push({ code: `test.${code}`, severity: "error", message });
+  };
+  validateStructure(test, reject);
+  validateDeclarations(test, reject);
+  validateExpressions(test, diagnostics, reject);
+  validateGraph(test, reject);
+  if (diagnostics.length) return { ok: false, diagnostics };
+  // SAFETY: Validation establishes nonempty sections/items, scalar declarations, expression types
+  // and forward edges. Clone so later mutation of the caller's definition cannot invalidate the brand.
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- SAFETY: Sole constructor of the validated executable test brand.
+  return { ok: true, value: copyExecutableDefinition(test) as QtiExecutableTest };
+}
+
+function validateStructure(test: QtiTestDefinition, reject: Reject): void {
+  const identifiers = new Set<string>();
+  const identifier = (value: string) => {
+    if (
+      !isQtiIdentifier(value) ||
+      ["EXIT_TEST", "__proto__", "constructor", "prototype"].includes(value) ||
+      identifiers.has(value)
+    )
+      reject("identifier", "Test identifiers must be valid, unique and non-reserved.");
+    identifiers.add(value);
+  };
+  identifier(test.identifier);
+  identifier(test.partIdentifier);
+  for (const declaration of test.outcomeDeclarations) identifier(declaration.identifier);
+  if (!test.title.trim() || !test.sections.length)
+    reject("structure", "A test requires a title and at least one section.");
+  const hrefs = new Set<string>();
+  for (const section of test.sections) {
+    identifier(section.identifier);
+    if (!section.title.trim() || !section.items.length)
+      reject("section.empty", "Sections require a title and at least one item.");
+    for (const item of section.items) {
+      identifier(item.identifier);
+      if (!isQtiPackageItemHref(item.href) || hrefs.has(item.href))
+        reject("item.href", "Item references must have distinct package-local paths.");
+      hrefs.add(item.href);
+      if (item.categories.some((category) => !isQtiIdentifier(category)))
+        reject("item.category", "Item categories must be QTI identifiers.");
+    }
+  }
+}
+
+function validateDeclarations(test: QtiTestDefinition, reject: Reject): void {
+  for (const declaration of test.outcomeDeclarations) {
+    if (
+      declaration.cardinality !== "single" ||
+      declaration.lookupTable !== undefined ||
+      !isTestBaseType(declaration.baseType)
+    )
+      reject(
+        "declaration.unsupported",
+        "Test outcomes require a supported single-cardinality base type without lookup tables.",
+      );
+    if (
+      declaration.defaultValue !== null &&
+      !isTestScalarValue(declaration.baseType, declaration.defaultValue)
+    )
+      reject("declaration.default", "Test outcome default does not match its declared type.");
+  }
+}
+
+function validateExpressions(
+  test: QtiTestDefinition,
+  diagnostics: QtiDiagnostic[],
+  reject: Reject,
+): void {
+  const declarations = new Map(
+    test.outcomeDeclarations.map((declaration) => [declaration.identifier, declaration]),
+  );
+  const categories = new Set(
+    test.sections.flatMap((section) => section.items.flatMap((item) => item.categories)),
+  );
+  for (const section of test.sections) {
+    for (const branch of section.branches) {
+      if (
+        !isBoolean(
+          checkTestExpression(branch.expression, declarations, categories, "branch", diagnostics),
+        )
+      )
+        reject("branch.expression", "Branch expressions must produce a boolean.");
+    }
+  }
+  for (const rule of test.outcomeProcessing) {
+    const target = declarations.get(rule.identifier);
+    const actual = checkTestExpression(
+      rule.expression,
+      declarations,
+      categories,
+      "outcome",
+      diagnostics,
+    );
+    const compatible =
+      actual &&
+      target &&
+      (actual.baseType === target.baseType ||
+        (actual.baseType === "integer" && target.baseType === "float"));
+    if (!compatible || actual.cardinality !== "single")
+      reject("outcome.type", "Outcome rules must assign the declared outcome type.");
+  }
+}
+
+function validateGraph(test: QtiTestDefinition, reject: Reject): void {
+  const indices = new Map(test.sections.map((section, index) => [section.identifier, index]));
+  for (const [index, section] of test.sections.entries()) {
+    for (const branch of section.branches) {
+      if (branch.target !== "EXIT_TEST" && (indices.get(branch.target) ?? -1) <= index)
+        reject("branch.target", "Branch targets must identify a later section or EXIT_TEST.");
+    }
+  }
+}
+
+function copyExecutableDefinition(test: QtiTestDefinition): QtiTestDefinition {
+  return Object.freeze({
+    ...test,
+    outcomeDeclarations: Object.freeze(
+      test.outcomeDeclarations.map((declaration) =>
+        Object.freeze({
+          ...declaration,
+          attributes: { ...declaration.attributes },
+        }),
+      ),
+    ),
+    outcomeProcessing: Object.freeze(
+      test.outcomeProcessing.map((rule) =>
+        Object.freeze({ ...rule, expression: copyExpression(rule.expression) }),
+      ),
+    ),
+    sections: Object.freeze(
+      test.sections.map((section) =>
+        Object.freeze({
+          ...section,
+          items: Object.freeze(
+            section.items.map((item) =>
+              Object.freeze({ ...item, categories: Object.freeze([...item.categories]) }),
+            ),
+          ),
+          branches: Object.freeze(
+            section.branches.map((branch) =>
+              Object.freeze({ ...branch, expression: copyExpression(branch.expression) }),
+            ),
+          ),
+        }),
+      ),
+    ),
+  });
+}
+
+function copyExpression(expression: QtiTestExpression): QtiTestExpression {
+  switch (expression.type) {
+    case "sum":
+    case "and":
+    case "or":
+      return Object.freeze({
+        ...expression,
+        expressions: Object.freeze(expression.expressions.map(copyExpression)),
+      });
+    case "numericCompare":
+      return Object.freeze({
+        ...expression,
+        left: copyExpression(expression.left),
+        right: copyExpression(expression.right),
+      });
+    case "not":
+      return Object.freeze({ ...expression, expression: copyExpression(expression.expression) });
+    case "baseValue":
+    case "variable":
+    case "testVariables":
+      return Object.freeze({ ...expression });
+    default:
+      return assertNever(expression);
+  }
+}

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/types.ts

@@ -770,6 +770,7 @@ export interface QtiScoreResult {
 export type QtiElementSupport =
   | QtiInteractionElementSupport
   | QtiProcessingElementSupport
+  | QtiTestElementSupport
   | QtiItemMetadataElementSupport;
 
 interface QtiElementSupportBase {
@@ -794,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";
 }