@longsightgroup/qti3-core 0.11.0 → 0.12.1

package/src/test-expression-validation.ts

@@ -0,0 +1,139 @@
+import { assertNever } from "./assert-never.js";
+import {
+  isTestBaseType,
+  testExpressionSyntax,
+  type QtiTestBaseType,
+  type QtiTestExpression,
+} from "./test-expression.js";
+import type { QtiDiagnostic, QtiOutcomeDeclaration, QtiValue } from "./types.js";
+
+/** The declared QTI type of an expression, including its cardinality. */
+export interface TestExpressionType {
+  readonly baseType: QtiTestBaseType;
+  readonly cardinality: "single" | "multiple";
+}
+
+/** Check scalar literals and defaults against the supported base types. */
+export function isTestScalarValue(baseType: string | undefined, value: QtiValue): boolean {
+  if (baseType === undefined) return false;
+  switch (baseType) {
+    case "integer":
+      return typeof value === "number" && Number.isSafeInteger(value);
+    case "float":
+      return typeof value === "number" && Number.isFinite(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "string":
+    case "identifier":
+      return typeof value === "string";
+    default:
+      return false;
+  }
+}
+
+/** Infer a test expression's QTI type and diagnose invalid operands and scope. */
+export function checkTestExpression(
+  expression: QtiTestExpression,
+  declarations: ReadonlyMap<string, QtiOutcomeDeclaration>,
+  categories: ReadonlySet<string>,
+  scope: "outcome" | "branch",
+  diagnostics: QtiDiagnostic[],
+): TestExpressionType | undefined {
+  const reject = (code: string, message: string) => {
+    diagnostics.push({
+      code: `test.${code}`,
+      severity: "error",
+      message,
+      source: expression.source,
+    });
+  };
+  const check = (child: QtiTestExpression) =>
+    checkTestExpression(child, declarations, categories, scope, diagnostics);
+  if (!testExpressionSyntax.some((syntax) => syntax.type === expression.type)) {
+    reject("expression.unsupported", "Expression is outside the supported test execution profile.");
+    return undefined;
+  }
+  switch (expression.type) {
+    case "baseValue":
+      if (!isTestScalarValue(expression.baseType, expression.value)) {
+        reject("expression.value", "Expression values must match a supported scalar base type.");
+        return undefined;
+      }
+      return { baseType: expression.baseType, cardinality: "single" };
+    case "variable": {
+      const declaration = declarations.get(expression.identifier);
+      if (!declaration || !isTestBaseType(declaration.baseType)) {
+        reject(
+          "expression.variable",
+          "Test expression references an undeclared or unsupported outcome.",
+        );
+        return undefined;
+      }
+      return { baseType: declaration.baseType, cardinality: "single" };
+    }
+    case "testVariables":
+      if (scope === "branch")
+        reject(
+          "branch.scope",
+          "Test-variable aggregation belongs in outcome processing, not a branch rule.",
+        );
+      if (
+        expression.variableIdentifier !== "SCORE" ||
+        (expression.includeCategory !== undefined && !categories.has(expression.includeCategory))
+      )
+        reject(
+          "expression.testVariables",
+          "This test profile aggregates item SCORE values from declared categories.",
+        );
+      return { baseType: "float", cardinality: "multiple" };
+    case "sum": {
+      const operands = expression.expressions.map(check);
+      if (!operands.length || operands.some((type) => !isNumeric(type)))
+        reject("expression.sum", "Test sums require numeric operands.");
+      return {
+        baseType: operands.every((type) => type?.baseType === "integer") ? "integer" : "float",
+        cardinality: "single",
+      };
+    }
+    case "numericCompare": {
+      const left = check(expression.left);
+      const right = check(expression.right);
+      if (
+        !testExpressionSyntax.some(
+          (syntax) => syntax.type === "numericCompare" && syntax.operator === expression.operator,
+        )
+      )
+        reject("expression.compare", "Unsupported test comparison operator.");
+      if (
+        !isNumeric(left) ||
+        left?.cardinality !== "single" ||
+        !isNumeric(right) ||
+        right?.cardinality !== "single"
+      )
+        reject("expression.compare", "Test comparisons require two scalar numbers.");
+      return { baseType: "boolean", cardinality: "single" };
+    }
+    case "and":
+    case "or": {
+      const operands = expression.expressions.map(check);
+      if (!operands.length || operands.some((type) => !isBoolean(type)))
+        reject("expression.boolean", "Test logic requires boolean operands.");
+      return { baseType: "boolean", cardinality: "single" };
+    }
+    case "not":
+      if (!isBoolean(check(expression.expression)))
+        reject("expression.boolean", "Test logic requires a boolean operand.");
+      return { baseType: "boolean", cardinality: "single" };
+    default:
+      return assertNever(expression);
+  }
+}
+
+function isNumeric(type: TestExpressionType | undefined): boolean {
+  return type?.baseType === "integer" || type?.baseType === "float";
+}
+
+/** Whether a branch expression has the required single boolean type. */
+export function isBoolean(type: TestExpressionType | undefined): boolean {
+  return type?.baseType === "boolean" && type.cardinality === "single";
+}

package/src/test-expression.ts

@@ -0,0 +1,66 @@
+import type { QtiSourceLocation } from "./types.js";
+
+/** Scalar types supported by deterministic test outcome processing. */
+export type QtiTestBaseType = "integer" | "float" | "boolean" | "string" | "identifier";
+
+/** Test expressions form a closed language, independent of item processing. */
+export type QtiTestExpression = (
+  | {
+      readonly type: "baseValue";
+      readonly baseType: QtiTestBaseType;
+      readonly value: number | boolean | string;
+    }
+  | { readonly type: "variable"; readonly identifier: string }
+  | {
+      readonly type: "testVariables";
+      readonly variableIdentifier: string;
+      readonly includeCategory?: string | undefined;
+    }
+  | { readonly type: "sum"; readonly expressions: readonly QtiTestExpression[] }
+  | { readonly type: "and"; readonly expressions: readonly QtiTestExpression[] }
+  | { readonly type: "or"; readonly expressions: readonly QtiTestExpression[] }
+  | {
+      readonly type: "numericCompare";
+      readonly operator: "gt" | "gte" | "lt" | "lte";
+      readonly left: QtiTestExpression;
+      readonly right: QtiTestExpression;
+    }
+  | { readonly type: "not"; readonly expression: QtiTestExpression }
+) & { readonly source?: QtiSourceLocation | undefined };
+
+/** XML names, AST variants, arities and attributes owned by the test language. */
+export const testExpressionSyntax = [
+  { name: "qti-base-value", type: "baseValue", arity: 0, attributes: ["base-type"] },
+  { name: "qti-variable", type: "variable", arity: 0, attributes: ["identifier"] },
+  {
+    name: "qti-test-variables",
+    type: "testVariables",
+    arity: 0,
+    attributes: ["variable-identifier", "include-category"],
+  },
+  { name: "qti-sum", type: "sum", arity: "oneOrMore", attributes: [] },
+  { name: "qti-gt", type: "numericCompare", operator: "gt", arity: 2, attributes: [] },
+  { name: "qti-gte", type: "numericCompare", operator: "gte", arity: 2, attributes: [] },
+  { name: "qti-lt", type: "numericCompare", operator: "lt", arity: 2, attributes: [] },
+  { name: "qti-lte", type: "numericCompare", operator: "lte", arity: 2, attributes: [] },
+  { name: "qti-and", type: "and", arity: "oneOrMore", attributes: [] },
+  { name: "qti-or", type: "or", arity: "oneOrMore", attributes: [] },
+  { name: "qti-not", type: "not", arity: 1, attributes: [] },
+] as const satisfies readonly {
+  name: string;
+  type: QtiTestExpression["type"];
+  operator?: "gt" | "gte" | "lt" | "lte";
+  arity: number | "oneOrMore";
+  attributes: readonly string[];
+}[];
+
+/** Refine a supported test scalar type without accepting item-only base types. */
+export function isTestBaseType(value: string | undefined): value is QtiTestBaseType {
+  return (
+    value === "integer" ||
+    value === "float" ||
+    value === "boolean" ||
+    value === "string" ||
+    value === "identifier"
+  );
+}

package/src/test-model.ts

@@ -0,0 +1,68 @@
+import type { QtiDiagnostic, QtiOutcomeDeclaration } from "./types.js";
+import type { QtiTestBaseType, QtiTestExpression } from "./test-expression.js";
+
+/** An ordered branch evaluated after the section's final item submission. */
+export interface QtiTestBranch {
+  readonly target: string;
+  readonly expression: QtiTestExpression;
+}
+
+/** A fixed item reference; categories participate in test-variable aggregation. */
+export interface QtiTestItemRef {
+  readonly identifier: string;
+  readonly href: string;
+  readonly categories: readonly string[];
+}
+
+/** A flat section in the supported linear, individually submitted test profile. */
+export interface QtiTestSection {
+  readonly identifier: string;
+  readonly title: string;
+  readonly items: readonly QtiTestItemRef[];
+  readonly branches: readonly QtiTestBranch[];
+}
+
+/** Framework-neutral QTI test definition. Validation establishes executable support. */
+export interface QtiTestDefinition {
+  readonly identifier: string;
+  readonly title: string;
+  readonly partIdentifier: string;
+  readonly sections: readonly QtiTestSection[];
+  readonly outcomeDeclarations: readonly QtiOutcomeDeclaration[];
+  readonly outcomeProcessing: readonly QtiTestOutcomeRule[];
+}
+
+/** Sequential assignment of a test expression to a declared test outcome. */
+export interface QtiTestOutcomeRule {
+  readonly type: "setOutcomeValue";
+  readonly identifier: string;
+  readonly expression: QtiTestExpression;
+}
+
+type ExecutableSection = QtiTestSection & {
+  readonly items: readonly [QtiTestItemRef, ...QtiTestItemRef[]];
+};
+type ExecutableOutcome = Readonly<QtiOutcomeDeclaration> & {
+  readonly cardinality: "single";
+  readonly baseType: QtiTestBaseType;
+  readonly defaultValue: number | boolean | string | null;
+};
+
+declare const executableTest: unique symbol;
+
+/** A test checked for supported expressions, unique identifiers and forward routing. */
+export type QtiExecutableTest = Omit<QtiTestDefinition, "sections" | "outcomeDeclarations"> & {
+  readonly [executableTest]: true;
+  readonly sections: readonly [ExecutableSection, ...ExecutableSection[]];
+  readonly outcomeDeclarations: readonly ExecutableOutcome[];
+};
+
+/** Typed failure channel shared by test construction, parsing and transitions. */
+export type QtiTestResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly diagnostics: readonly QtiDiagnostic[] };
+
+/** Construct a safe test diagnostic without including submitted content. */
+export function testFailure(code: string, message: string): QtiTestResult<never> {
+  return { ok: false, diagnostics: [{ code: `test.${code}`, severity: "error", message }] };
+}

package/src/test-parser.ts

@@ -0,0 +1,201 @@
+import { parseOutcomeDeclaration } from "./parser-declarations.js";
+import { QTI_ASI_NAMESPACE } from "./qti-namespaces.js";
+import { parseXmlTree, type XmlNode } from "./xml.js";
+import { validateQtiTest } from "./test-validation.js";
+import { parseTestExpressionChild } from "./test-expression-parser.js";
+import { testExpressionSyntax } from "./test-expression.js";
+import { checkTestXml, rejectTestXml } from "./test-xml.js";
+import {
+  testFailure,
+  type QtiExecutableTest,
+  type QtiTestBranch,
+  type QtiTestOutcomeRule,
+  type QtiTestResult,
+  type QtiTestSection,
+} from "./test-model.js";
+import type { QtiDiagnostic, QtiOutcomeDeclaration } from "./types.js";
+
+/** Whether a test requires runtime selection rather than ordinary fixed navigation. */
+export type QtiTestExecution =
+  | { readonly kind: "fixed" }
+  | { readonly kind: "sequenced"; readonly test: QtiExecutableTest };
+
+/** Classify sequencing on the parsed tree and reject unsupported executable routes. */
+export function parseQtiTestExecution(xml: string): QtiTestResult<QtiTestExecution> {
+  const parsed = parseTestRoot(xml);
+  if (!parsed.ok) return parsed;
+  if (!requiresSequence(parsed.value)) return { ok: true, value: { kind: "fixed" } };
+  const result = parseTestDefinition(parsed.value);
+  return result.ok ? { ok: true, value: { kind: "sequenced", test: result.value } } : result;
+}
+
+/** Parse the supported executable test profile; never silently ignore routing features. */
+export function parseQtiTest(xml: string): QtiTestResult<QtiExecutableTest> {
+  const parsed = parseTestRoot(xml);
+  return parsed.ok ? parseTestDefinition(parsed.value) : parsed;
+}
+
+function parseTestRoot(xml: string): QtiTestResult<XmlNode> {
+  const { root, errors } = parseXmlTree(xml);
+  if (
+    errors.length ||
+    !root ||
+    root.localName !== "qti-assessment-test" ||
+    root.uri !== QTI_ASI_NAMESPACE
+  )
+    return testFailure("xml", "Expected a well-formed QTI 3 assessment test.");
+  return { ok: true, value: root };
+}
+
+function requiresSequence(node: XmlNode): boolean {
+  return (
+    (node.uri === QTI_ASI_NAMESPACE &&
+      [
+        "qti-branch-rule",
+        "qti-pre-condition",
+        "qti-selection",
+        "qti-ordering",
+        "qti-adaptive-selection",
+      ].includes(node.localName)) ||
+    node.children.some(requiresSequence)
+  );
+}
+
+function parseTestDefinition(root: XmlNode): QtiTestResult<QtiExecutableTest> {
+  const diagnostics: QtiDiagnostic[] = [];
+  checkTestXml(
+    root,
+    ["qti-outcome-declaration", "qti-test-part", "qti-outcome-processing"],
+    ["identifier", "title", "tool-name", "tool-version"],
+    diagnostics,
+  );
+  const part = parseTestPart(root, diagnostics);
+  if (!part.ok) return part;
+  const declarations = root.children
+    .filter((node) => node.localName === "qti-outcome-declaration")
+    .map((node) => parseTestDeclaration(node, diagnostics));
+  const sections = part.value.children
+    .filter((node) => node.localName === "qti-assessment-section")
+    .map((node) => parseTestSection(node, diagnostics));
+  const rules = parseTestOutcomeProcessing(root, diagnostics);
+  if (diagnostics.length) return { ok: false, diagnostics };
+  return validateQtiTest({
+    identifier: root.attributes.identifier ?? "",
+    title: root.attributes.title ?? "",
+    partIdentifier: part.value.attributes.identifier ?? "",
+    sections,
+    outcomeDeclarations: declarations,
+    outcomeProcessing: rules,
+  });
+}
+
+function parseTestPart(root: XmlNode, diagnostics: QtiDiagnostic[]): QtiTestResult<XmlNode> {
+  const parts = root.children.filter((node) => node.localName === "qti-test-part");
+  const part = parts[0];
+  if (
+    parts.length !== 1 ||
+    !part ||
+    part.attributes["navigation-mode"] !== "linear" ||
+    part.attributes["submission-mode"] !== "individual"
+  )
+    return testFailure(
+      "mode",
+      "Executable tests require one linear part with individual submission.",
+    );
+  checkTestXml(
+    part,
+    ["qti-assessment-section"],
+    ["identifier", "navigation-mode", "submission-mode"],
+    diagnostics,
+  );
+  return { ok: true, value: part };
+}
+
+function parseTestDeclaration(node: XmlNode, diagnostics: QtiDiagnostic[]): QtiOutcomeDeclaration {
+  if (node.attributes.cardinality !== "single" || node.children.length > 1)
+    rejectTestXml(node, diagnostics);
+  checkTestXml(
+    node,
+    ["qti-default-value"],
+    ["identifier", "cardinality", "base-type"],
+    diagnostics,
+  );
+  for (const value of node.children) {
+    checkTestXml(value, ["qti-value"], [], diagnostics);
+    if (value.children.length !== 1) rejectTestXml(value, diagnostics);
+    for (const scalar of value.children) checkTestXml(scalar, [], [], diagnostics, true);
+  }
+  return parseOutcomeDeclaration(node, diagnostics);
+}
+
+function parseTestSection(section: XmlNode, diagnostics: QtiDiagnostic[]): QtiTestSection {
+  checkTestXml(
+    section,
+    ["qti-assessment-item-ref", "qti-branch-rule"],
+    ["identifier", "title", "visible", "keep-together"],
+    diagnostics,
+  );
+  if (
+    !["true", "1"].includes(section.attributes.visible ?? "") ||
+    (section.attributes["keep-together"] !== undefined &&
+      !["true", "1"].includes(section.attributes["keep-together"]))
+  )
+    rejectTestXml(section, diagnostics);
+  const branches: QtiTestBranch[] = [];
+  for (const branch of section.children.filter((node) => node.localName === "qti-branch-rule")) {
+    checkTestXml(
+      branch,
+      testExpressionSyntax.map((syntax) => syntax.name),
+      ["target"],
+      diagnostics,
+    );
+    const expression = parseTestExpressionChild(branch, diagnostics);
+    if (expression) branches.push({ target: branch.attributes.target ?? "", expression });
+  }
+  const items = section.children
+    .filter((node) => node.localName === "qti-assessment-item-ref")
+    .map((item) => {
+      checkTestXml(item, [], ["identifier", "href", "category"], diagnostics);
+      return {
+        identifier: item.attributes.identifier ?? "",
+        href: item.attributes.href ?? "",
+        categories: (item.attributes.category ?? "")
+          .split(/\s+/)
+          .filter((category) => category.length > 0),
+      };
+    });
+  return {
+    identifier: section.attributes.identifier ?? "",
+    title: section.attributes.title ?? "",
+    branches,
+    items,
+  };
+}
+
+function parseTestOutcomeProcessing(
+  root: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiTestOutcomeRule[] {
+  const processing = root.children.filter((node) => node.localName === "qti-outcome-processing");
+  if (processing.length > 1) rejectTestXml(root, diagnostics);
+  const rules: QtiTestOutcomeRule[] = [];
+  for (const node of processing) {
+    checkTestXml(node, ["qti-set-outcome-value"], [], diagnostics);
+    for (const rule of node.children) {
+      checkTestXml(
+        rule,
+        testExpressionSyntax.map((syntax) => syntax.name),
+        ["identifier"],
+        diagnostics,
+      );
+      const expression = parseTestExpressionChild(rule, diagnostics);
+      if (expression)
+        rules.push({
+          type: "setOutcomeValue",
+          identifier: rule.attributes.identifier ?? "",
+          expression,
+        });
+    }
+  }
+  return rules;
+}

package/src/test-processing.ts

@@ -0,0 +1,107 @@
+import { assertNever } from "./assert-never.js";
+import type { QtiTestExpression } from "./test-expression.js";
+import type { QtiExecutableTest } from "./test-model.js";
+
+/** Trusted server-scored submission. Item scores are finite scalar numbers. */
+export interface QtiTestSubmission {
+  readonly itemRef: string;
+  readonly score: number;
+}
+
+type TestValue = number | boolean | string | number[] | null;
+
+/** Data used by the deterministic test interpreter; no item session state or hooks. */
+export interface TestExpressionValues {
+  readonly outcomes: Readonly<Record<string, TestValue>>;
+  readonly submissions: readonly QtiTestSubmission[];
+  readonly categories: ReadonlyMap<string, readonly string[]>;
+}
+
+/** Evaluate a validated test expression using QTI null and three-valued boolean semantics. */
+export function evaluateTestExpression(
+  expression: QtiTestExpression,
+  values: TestExpressionValues,
+): TestValue {
+  const evaluate = (child: QtiTestExpression) => evaluateTestExpression(child, values);
+  switch (expression.type) {
+    case "baseValue":
+      return expression.value;
+    case "variable":
+      return values.outcomes[expression.identifier] ?? null;
+    case "testVariables": {
+      const scores = values.submissions
+        .filter(
+          (submission) =>
+            expression.includeCategory === undefined ||
+            values.categories.get(submission.itemRef)?.includes(expression.includeCategory),
+        )
+        .map((submission) => submission.score);
+      return scores.length ? scores : null;
+    }
+    case "sum": {
+      let sum = 0;
+      for (const child of expression.expressions) {
+        const value = evaluate(child);
+        if (value === null) return null;
+        if (typeof value === "number") sum += value;
+        else if (typeof value === "object") for (const number of value) sum += number;
+        else return null;
+      }
+      return sum;
+    }
+    case "numericCompare": {
+      const left = evaluate(expression.left);
+      const right = evaluate(expression.right);
+      if (typeof left !== "number" || typeof right !== "number") return null;
+      switch (expression.operator) {
+        case "gt":
+          return left > right;
+        case "gte":
+          return left >= right;
+        case "lt":
+          return left < right;
+        case "lte":
+          return left <= right;
+        default:
+          return assertNever(expression.operator);
+      }
+    }
+    case "and":
+    case "or": {
+      const decisive = expression.type === "or";
+      let sawNull = false;
+      for (const child of expression.expressions) {
+        const value = evaluate(child);
+        if (value === decisive) return decisive;
+        if (value === null) sawNull = true;
+      }
+      return sawNull ? null : !decisive;
+    }
+    case "not": {
+      const value = evaluate(expression.expression);
+      return value === null ? null : !value;
+    }
+    default:
+      return assertNever(expression);
+  }
+}
+
+/** Recompute outcomes from defaults and committed scores, in assignment order. */
+export function processTestOutcomes(
+  test: QtiExecutableTest,
+  submissions: readonly QtiTestSubmission[],
+): { readonly outcomes: Record<string, TestValue> } {
+  const outcomes: Record<string, TestValue> = Object.fromEntries(
+    test.outcomeDeclarations.map((d) => [d.identifier, d.defaultValue]),
+  );
+  const categories = new Map(
+    test.sections.flatMap((s) => s.items.map((i) => [i.identifier, i.categories] as const)),
+  );
+  for (const rule of test.outcomeProcessing)
+    outcomes[rule.identifier] = evaluateTestExpression(rule.expression, {
+      outcomes,
+      submissions,
+      categories,
+    });
+  return { outcomes };
+}