@longsightgroup/qti3-core 0.9.1 → 0.9.3

package/src/attempt-state.ts

@@ -0,0 +1,245 @@
+import type {
+  QtiAttemptStateV1,
+  QtiAttemptStatus,
+  QtiDiagnostic,
+  QtiDocument,
+  QtiPortableCustomStateValue,
+  QtiScalarValue,
+  QtiValue,
+  QtiVariableDeclaration,
+} from "./types.js";
+import {
+  ATTEMPT_STATE_SCHEMA,
+  COMPLETION_COMPLETED,
+  COMPLETION_NOT_ATTEMPTED,
+  COMPLETION_STATUS,
+  COMPLETION_UNKNOWN,
+} from "./attempt-state-constants.js";
+import { isQtiPortableCustomStateValue, isQtiValue, qtiValueToString } from "./value-format.js";
+import { isRecordValue } from "./processing-values.js";
+import { isPair, isPoint } from "./validation-primitives.js";
+
+export function isQtiAttemptStateV1(value: unknown): value is QtiAttemptStateV1 {
+  return attemptStateErrors(value).length === 0;
+}
+
+export function assertQtiAttemptStateV1(value: unknown): asserts value is QtiAttemptStateV1 {
+  const [firstError] = attemptStateErrors(value);
+  if (firstError) throw new Error(firstError);
+}
+
+export function assertCompatiblePriorState(
+  document: QtiDocument,
+  priorState: QtiAttemptStateV1 | undefined,
+): void {
+  if (!priorState) return;
+  assertQtiAttemptStateV1(priorState);
+  if (priorState.itemIdentifier !== document.item.identifier) {
+    throw new Error(
+      `Cannot restore state for ${priorState.itemIdentifier} into ${document.item.identifier}.`,
+    );
+  }
+  const responseIdentifiers = new Set(
+    document.item.responseDeclarations.map((declaration) => declaration.identifier),
+  );
+  const outcomeIdentifiers = new Set([
+    ...document.item.outcomeDeclarations.map((declaration) => declaration.identifier),
+    COMPLETION_STATUS,
+  ]);
+  const templateIdentifiers = new Set(
+    document.item.templateDeclarations.map((declaration) => declaration.identifier),
+  );
+  const interactionStateIdentifiers = new Set(
+    document.item.interactions
+      .filter((interaction) => interaction.type === "portableCustom")
+      .map((interaction) => interaction.responseIdentifier)
+      .filter((identifier): identifier is string => Boolean(identifier)),
+  );
+  assertKnownStateIdentifiers("response", priorState.responses, responseIdentifiers);
+  assertKnownStateIdentifiers("outcome", priorState.outcomes, outcomeIdentifiers);
+  assertKnownStateIdentifiers("template", priorState.templateValues ?? {}, templateIdentifiers);
+  assertKnownPortableCustomStateIdentifiers(
+    priorState.interactionStates ?? {},
+    interactionStateIdentifiers,
+  );
+  for (const message of priorState.validationMessages) {
+    if (message.path && !responseIdentifiers.has(message.path)) {
+      throw new Error(`Cannot restore validation message for unknown response ${message.path}.`);
+    }
+  }
+  for (const declaration of document.item.responseDeclarations) {
+    assertRestoredValueMatchesDeclaration("response", declaration, priorState.responses);
+  }
+  for (const declaration of document.item.outcomeDeclarations) {
+    assertRestoredValueMatchesDeclaration("outcome", declaration, priorState.outcomes);
+  }
+  for (const declaration of document.item.templateDeclarations) {
+    assertRestoredValueMatchesDeclaration("template", declaration, priorState.templateValues ?? {});
+  }
+  const completionStatus = priorState.outcomes[COMPLETION_STATUS];
+  if (
+    completionStatus !== undefined &&
+    completionStatus !== COMPLETION_NOT_ATTEMPTED &&
+    completionStatus !== COMPLETION_UNKNOWN &&
+    completionStatus !== COMPLETION_COMPLETED &&
+    completionStatus !== "incomplete"
+  ) {
+    throw new Error(
+      `Cannot restore unsupported completionStatus ${qtiValueToString(completionStatus)}.`,
+    );
+  }
+}
+
+function assertKnownStateIdentifiers(
+  kind: string,
+  record: Record<string, QtiValue>,
+  allowed: Set<string>,
+): void {
+  const unknown = Object.keys(record).find((identifier) => !allowed.has(identifier));
+  if (unknown) throw new Error(`Cannot restore unknown ${kind} identifier ${unknown}.`);
+}
+
+function assertKnownPortableCustomStateIdentifiers(
+  record: Record<string, QtiPortableCustomStateValue>,
+  allowed: Set<string>,
+): void {
+  const unknown = Object.keys(record).find((identifier) => !allowed.has(identifier));
+  if (unknown) throw new Error(`Cannot restore unknown interaction state identifier ${unknown}.`);
+}
+
+function assertRestoredValueMatchesDeclaration(
+  kind: string,
+  declaration: QtiVariableDeclaration,
+  record: Record<string, QtiValue>,
+): void {
+  if (!(declaration.identifier in record)) return;
+  const value = record[declaration.identifier] ?? null;
+  const error = restoredValueError(declaration, value);
+  if (error) throw new Error(`Cannot restore ${kind} ${declaration.identifier}: ${error}.`);
+}
+
+function restoredValueError(
+  declaration: QtiVariableDeclaration,
+  value: QtiValue,
+): string | undefined {
+  if (value === null) return undefined;
+  if (declaration.cardinality === "record") {
+    return isRecordValue(value) ? undefined : "expected record value";
+  }
+  if (isRecordValue(value)) return "expected scalar value";
+  if (declaration.cardinality === "single" && Array.isArray(value)) {
+    return "expected single value";
+  }
+  if (
+    (declaration.cardinality === "multiple" || declaration.cardinality === "ordered") &&
+    !Array.isArray(value)
+  ) {
+    return `expected ${declaration.cardinality} value container`;
+  }
+  if (!declaration.baseType) return undefined;
+  for (const entry of restoredValueEntries(value)) {
+    if (!restoredScalarMatchesBaseType(entry, declaration.baseType)) {
+      return `value ${String(entry)} is not valid for base-type ${declaration.baseType}`;
+    }
+  }
+  return undefined;
+}
+
+function restoredValueEntries(value: QtiValue): QtiScalarValue[] {
+  if (value === null || isRecordValue(value)) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function restoredScalarMatchesBaseType(
+  value: QtiScalarValue,
+  baseType: QtiVariableDeclaration["baseType"],
+): boolean {
+  if (!baseType) return true;
+  if (baseType === "integer") {
+    return typeof value === "number" ? Number.isInteger(value) : /^-?\d+$/.test(String(value));
+  }
+  if (baseType === "float") {
+    return typeof value === "number" ? Number.isFinite(value) : Number.isFinite(Number(value));
+  }
+  if (baseType === "boolean")
+    return typeof value === "boolean" || value === "true" || value === "false";
+  if (baseType === "point") return isPoint(String(value));
+  if (baseType === "pair" || baseType === "directedPair") return isPair(String(value));
+  if (baseType === "identifier")
+    return typeof value === "string" && value.trim().length > 0 && !/\s/.test(value);
+  return typeof value === "string";
+}
+
+function isAttemptStatus(value: string): value is QtiAttemptStatus {
+  return (
+    value === "initialized" ||
+    value === "interacting" ||
+    value === "suspended" ||
+    value === "completed"
+  );
+}
+
+function attemptStateErrors(value: unknown): string[] {
+  if (!isRecord(value)) return ["QTI attempt state must be an object."];
+
+  const schema = value.schema;
+  if (schema !== ATTEMPT_STATE_SCHEMA) {
+    return [`Unsupported QTI attempt state schema ${String(schema)}.`];
+  }
+
+  const errors: string[] = [];
+  if (typeof value.itemIdentifier !== "string" || value.itemIdentifier.length === 0) {
+    errors.push("QTI attempt state itemIdentifier must be a non-empty string.");
+  }
+  if (typeof value.status !== "string" || !isAttemptStatus(value.status)) {
+    errors.push(`QTI attempt state status ${String(value.status)} is not supported.`);
+  }
+  if (!isQtiValueRecord(value.responses)) {
+    errors.push("QTI attempt state responses must be a record of QTI values.");
+  }
+  if (!isQtiValueRecord(value.outcomes)) {
+    errors.push("QTI attempt state outcomes must be a record of QTI values.");
+  }
+  if (value.templateValues !== undefined && !isQtiValueRecord(value.templateValues)) {
+    errors.push("QTI attempt state templateValues must be a record of QTI values.");
+  }
+  if (
+    value.interactionStates !== undefined &&
+    !isPortableCustomStateRecord(value.interactionStates)
+  ) {
+    errors.push("QTI attempt state interactionStates must be a record of JSON values.");
+  }
+  if (!isDiagnosticArray(value.validationMessages)) {
+    errors.push("QTI attempt state validationMessages must be an array of diagnostics.");
+  }
+  return errors;
+}
+
+function isQtiValueRecord(value: unknown): value is Record<string, QtiValue> {
+  if (!isRecord(value)) return false;
+  return Object.values(value).every(isQtiValue);
+}
+
+function isPortableCustomStateRecord(
+  value: unknown,
+): value is Record<string, QtiPortableCustomStateValue> {
+  if (!isRecord(value)) return false;
+  return Object.values(value).every(isQtiPortableCustomStateValue);
+}
+
+function isDiagnosticArray(value: unknown): value is QtiDiagnostic[] {
+  if (!Array.isArray(value)) return false;
+  return value.every((item) => {
+    if (!isRecord(item)) return false;
+    if (typeof item.code !== "string" || item.code.length === 0) return false;
+    if (item.severity !== "info" && item.severity !== "warning" && item.severity !== "error") {
+      return false;
+    }
+    if (typeof item.message !== "string" || item.message.length === 0) return false;
+    return item.path === undefined || typeof item.path === "string";
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/catalog.ts

@@ -112,7 +112,7 @@ function selectedCandidates(
     .filter((entry): entry is { candidate: Candidate; index: number; rank: number } =>
       Number.isInteger(entry.rank),
     )
-    .sort((a, b) => a.rank - b.rank || a.index - b.index);
+    .toSorted((a, b) => a.rank - b.rank || a.index - b.index);
   if (languageMatches.length > 0) return languageMatches.map((entry) => entry.candidate);
   if (options.includeDefaultFallback === false) return [];
   const defaults = candidates.filter((candidate) => candidate.default);

package/src/content-text.ts

@@ -1,4 +1,5 @@
 import type { QtiChoice, QtiContentNode, QtiSourceLocation } from "./types.js";
+import { assertNever } from "./assert-never.js";
 
 export interface FlatTextFromContentOptions {
   excludeAnnotations?: boolean;
@@ -63,6 +64,8 @@ function flatTextFromContentNode(node: QtiContentNode, excludeAnnotations: boole
     case "interaction":
     case "printedVariable":
       return "";
+    default:
+      return assertNever(node);
   }
 }
 

package/src/custom-operators.ts

@@ -0,0 +1,12 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+
+export interface QtiCustomOperatorContext {
+  definition?: string | undefined;
+  className?: string | undefined;
+  attributes: Record<string, string>;
+  values: QtiValue[];
+  expression: Extract<QtiProcessingExpression, { type: "customOperator" }>;
+}
+
+export type QtiCustomOperatorHandler = (context: QtiCustomOperatorContext) => QtiValue;
+export type QtiCustomOperatorRegistry = Record<string, QtiCustomOperatorHandler>;

package/src/delivery-redaction.ts

@@ -0,0 +1,268 @@
+import type { QtiDiagnostic, QtiSourceLocation } from "./types.js";
+import { descendants, parseXmlTree, type XmlNode } from "./xml.js";
+
+export const DEFAULT_VALUE_DECLARATION_ELEMENT_NAMES = new Set([
+  "response-declaration",
+  "outcome-declaration",
+  "template-declaration",
+]);
+
+export const FORBIDDEN_DELIVERY_SECRET_ELEMENT_NAMES = new Set([
+  "correct-response",
+  "mapping",
+  "area-mapping",
+  "match-table",
+  "interpolation-table",
+  "response-processing",
+]);
+
+export type QtiDeliverySecurityFindingKind =
+  | "forbidden-delivery-element"
+  | "unsupported-secure-delivery-element"
+  | "unsupported-adaptive-response-processing";
+
+export interface QtiDeliverySecurityFinding {
+  kind: QtiDeliverySecurityFindingKind;
+  qtiName: string;
+  localName: string;
+  message: string;
+  source?: QtiSourceLocation | undefined;
+}
+
+export interface QtiDeliverySecurityAnalysis {
+  diagnostics: QtiDiagnostic[];
+  findings: QtiDeliverySecurityFinding[];
+  /** True when this exact XML contains no known answer/scoring/feedback delivery leaks. */
+  deliverySafe: boolean;
+  /** True when secure-delivery redaction can be attempted for this XML. */
+  secureDeliverySupported: boolean;
+}
+
+export interface ParsedDeliveryXml {
+  root: XmlNode | undefined;
+  diagnostics: QtiDiagnostic[];
+}
+
+export interface DeliveryRedactionPolicy {
+  isForbiddenElement(node: XmlNode, normalizedName: string): boolean;
+  unsupportedFinding?(
+    node: XmlNode,
+    normalizedName: string,
+    nodes: readonly XmlNode[],
+  ): QtiDeliverySecurityFinding | null;
+  diagnosticCodeForFinding(kind: QtiDeliverySecurityFindingKind): string;
+  forbiddenElementMessage(node: XmlNode): string;
+}
+
+export interface RedactedDeliveryXmlResult {
+  ok: boolean;
+  diagnostics: QtiDiagnostic[];
+  analysis: QtiDeliverySecurityAnalysis;
+  xml?: string | undefined;
+}
+
+export function parseDeliveryXml(xml: string): ParsedDeliveryXml {
+  let parsed: ReturnType<typeof parseXmlTree>;
+  try {
+    parsed = parseXmlTree(xml);
+  } catch (error) {
+    return {
+      root: undefined,
+      diagnostics: [
+        {
+          code: "xml.parse",
+          severity: "error",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+
+  const diagnostics: QtiDiagnostic[] = parsed.errors.map((error) => ({
+    code: "xml.parse",
+    severity: "error",
+    message: error.message,
+  }));
+  if (!parsed.root) {
+    diagnostics.push({
+      code: "xml.empty",
+      severity: "error",
+      message: "No XML root element was found.",
+    });
+  }
+  return { root: parsed.root, diagnostics };
+}
+
+export function analyzeDeliveryXml(
+  parsed: ParsedDeliveryXml,
+  policy: DeliveryRedactionPolicy,
+): QtiDeliverySecurityAnalysis {
+  const diagnostics = [...parsed.diagnostics];
+  const findings: QtiDeliverySecurityFinding[] = [];
+
+  if (parsed.root) {
+    const nodes = [parsed.root, ...descendants(parsed.root, () => true)];
+    for (const node of nodes) {
+      const normalizedName = normalizedQtiElementName(node.localName);
+      if (policy.isForbiddenElement(node, normalizedName)) {
+        findings.push({
+          kind: "forbidden-delivery-element",
+          qtiName: node.name,
+          localName: node.localName,
+          message: policy.forbiddenElementMessage(node),
+          source: node.source,
+        });
+      }
+
+      const unsupportedFinding = policy.unsupportedFinding?.(node, normalizedName, nodes);
+      if (unsupportedFinding) findings.push(unsupportedFinding);
+    }
+  }
+
+  diagnostics.push(
+    ...findings.map((finding) =>
+      findingToDiagnostic(finding, (kind) => policy.diagnosticCodeForFinding(kind)),
+    ),
+  );
+  const parseOk = parsed.diagnostics.every((diagnostic) => diagnostic.severity !== "error");
+
+  return {
+    diagnostics,
+    findings,
+    deliverySafe:
+      parseOk && !findings.some((finding) => finding.kind === "forbidden-delivery-element"),
+    secureDeliverySupported:
+      parseOk &&
+      !findings.some(
+        (finding) =>
+          finding.kind === "unsupported-secure-delivery-element" ||
+          finding.kind === "unsupported-adaptive-response-processing",
+      ),
+  };
+}
+
+export function redactDeliveryXml(
+  xml: string,
+  policy: DeliveryRedactionPolicy,
+): RedactedDeliveryXmlResult {
+  const parsed = parseDeliveryXml(xml);
+  const analysis = analyzeDeliveryXml(parsed, policy);
+  if (!analysis.secureDeliverySupported) {
+    return {
+      ok: false,
+      diagnostics: analysis.diagnostics,
+      analysis,
+    };
+  }
+
+  if (!parsed.root) {
+    return {
+      ok: false,
+      diagnostics: parsed.diagnostics,
+      analysis,
+    };
+  }
+
+  const redactionRanges = readRedactionRanges(
+    [parsed.root, ...descendants(parsed.root, () => true)],
+    (node, normalizedName) => policy.isForbiddenElement(node, normalizedName),
+  );
+  const redactedXml = removeSourceRanges(xml, redactionRanges);
+  const redactedAnalysis = analyzeDeliveryXml(parseDeliveryXml(redactedXml), policy);
+  if (!redactedAnalysis.deliverySafe || !redactedAnalysis.secureDeliverySupported) {
+    return {
+      ok: false,
+      diagnostics: [...analysis.diagnostics, ...redactedAnalysis.diagnostics],
+      analysis: redactedAnalysis,
+    };
+  }
+
+  return {
+    ok: true,
+    xml: redactedXml,
+    diagnostics: redactedAnalysis.diagnostics,
+    analysis: redactedAnalysis,
+  };
+}
+
+export function readRedactionRanges(
+  nodes: readonly XmlNode[],
+  shouldRedact: (node: XmlNode, normalizedName: string) => boolean,
+): RedactionRange[] {
+  const ranges = nodes.flatMap((node) => {
+    const normalizedName = normalizedQtiElementName(node.localName);
+    if (!shouldRedact(node, normalizedName)) return [];
+    return sourceRangeFor(node);
+  });
+  return mergeSourceRanges(ranges);
+}
+
+export function sourceRangeFor(node: XmlNode): RedactionRange[] {
+  const endOffset = node.sourceRange.endOffset;
+  if (node.sourceRange.startOffset < 0 || endOffset === undefined) return [];
+  return [{ startOffset: node.sourceRange.startOffset, endOffset }];
+}
+
+export function removeSourceRanges(xml: string, ranges: readonly RedactionRange[]): string {
+  let output = "";
+  let cursor = 0;
+  for (const range of ranges) {
+    output += xml.slice(cursor, range.startOffset);
+    cursor = range.endOffset;
+  }
+  return output + xml.slice(cursor);
+}
+
+export function normalizedQtiElementName(localName: string): string {
+  const lower = localName.toLowerCase();
+  return lower.startsWith("qti-") ? lower.slice("qti-".length) : lower;
+}
+
+export function parseXmlBoolean(value: string | undefined): boolean | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") return true;
+  if (normalized === "false" || normalized === "0") return false;
+  return undefined;
+}
+
+export function isDeclarationDefaultValue(node: XmlNode, normalizedName: string): boolean {
+  return (
+    normalizedName === "default-value" &&
+    DEFAULT_VALUE_DECLARATION_ELEMENT_NAMES.has(
+      normalizedQtiElementName(node.parent?.localName ?? ""),
+    )
+  );
+}
+
+export interface RedactionRange {
+  startOffset: number;
+  endOffset: number;
+}
+
+function mergeSourceRanges(ranges: readonly RedactionRange[]): RedactionRange[] {
+  const sorted = ranges.toSorted((left, right) => left.startOffset - right.startOffset);
+  const merged: RedactionRange[] = [];
+  for (const range of sorted) {
+    const last = merged.at(-1);
+    if (last && range.startOffset <= last.endOffset) {
+      last.endOffset = Math.max(last.endOffset, range.endOffset);
+      continue;
+    }
+    merged.push({ ...range });
+  }
+  return merged;
+}
+
+function findingToDiagnostic(
+  finding: QtiDeliverySecurityFinding,
+  diagnosticCodeForFinding: (kind: QtiDeliverySecurityFindingKind) => string,
+): QtiDiagnostic {
+  return {
+    code: diagnosticCodeForFinding(finding.kind),
+    severity: "error",
+    message: finding.message,
+    path: finding.source?.path,
+    source: finding.source,
+  };
+}