@longsightgroup/qti3-core 0.9.2 → 0.9.4

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-preparation.ts

@@ -0,0 +1,121 @@
+import { materializeAdaptiveCandidateView } from "./adaptive-turn-materializer.js";
+import type {
+  QtiDeliverySecurityAnalysis,
+  QtiDeliverySecurityFindingKind,
+  RedactedDeliveryXmlResult,
+} from "./delivery-redaction.js";
+import { buildQtiDeliverySafeXml } from "./delivery-security.js";
+import type { QtiDiagnostic, QtiValue } from "./types.js";
+
+export type QtiDeliveryPreparationMode = "static" | "server-materialized-adaptive";
+
+export type QtiDeliveryPreparationOptions =
+  | { mode: "static" }
+  | {
+      mode: "server-materialized-adaptive";
+      outcomes: Record<string, QtiValue>;
+      templateValues?: Record<string, QtiValue>;
+    };
+
+export interface QtiDeliveryPreparationResult {
+  ok: boolean;
+  mode: QtiDeliveryPreparationMode;
+  diagnostics: QtiDeliverySecurityAnalysis["diagnostics"];
+  analysis: QtiDeliverySecurityAnalysis;
+  candidateSafeXml?: string | undefined;
+}
+
+/** Prepare candidate-safe XML for a supported QTI delivery mode. */
+export function prepareQtiDeliveryXml(
+  xml: string,
+  options: QtiDeliveryPreparationOptions,
+): QtiDeliveryPreparationResult {
+  const redaction =
+    options.mode === "static"
+      ? buildQtiDeliverySafeXml(xml)
+      : materializeAdaptiveCandidateView({
+          itemXml: xml,
+          outcomes: options.outcomes,
+          ...(options.templateValues === undefined
+            ? {}
+            : { templateValues: options.templateValues }),
+        });
+
+  return {
+    ok: redaction.ok,
+    mode: options.mode,
+    diagnostics: normalizePreparationDiagnostics(redaction, options.mode),
+    analysis: redaction.analysis,
+    candidateSafeXml: redaction.xml,
+  };
+}
+
+function normalizePreparationDiagnostics(
+  redaction: RedactedDeliveryXmlResult,
+  mode: QtiDeliveryPreparationMode,
+): QtiDiagnostic[] {
+  const findingCodes = redaction.analysis.findings.map((finding) =>
+    preparationDiagnosticCodeForFinding(finding.kind, mode),
+  );
+  let findingIndex = 0;
+
+  return redaction.diagnostics.map((diagnostic) => {
+    if (!isDeliveryFindingDiagnosticCode(diagnostic.code)) return diagnostic;
+
+    if (diagnostic.code === "adaptiveTurn.materialization.unsupported") {
+      return {
+        ...diagnostic,
+        code: preparationDiagnosticCodeForLowerLevelCode(diagnostic.code, mode),
+      };
+    }
+
+    const code = findingCodes[findingIndex];
+    findingIndex += 1;
+
+    return {
+      ...diagnostic,
+      code: code ?? preparationDiagnosticCodeForLowerLevelCode(diagnostic.code, mode),
+    };
+  });
+}
+
+function preparationDiagnosticCodeForFinding(
+  kind: QtiDeliverySecurityFindingKind,
+  mode: QtiDeliveryPreparationMode,
+): string {
+  if (kind === "forbidden-delivery-element") return "delivery.preparation.forbiddenElement";
+  if (kind === "unsupported-adaptive-response-processing") {
+    return "delivery.preparation.unsupportedAdaptiveResponseProcessing";
+  }
+  return mode === "server-materialized-adaptive"
+    ? "delivery.preparation.unsupportedMaterialization"
+    : "delivery.preparation.unsupportedSecureDelivery";
+}
+
+function isDeliveryFindingDiagnosticCode(code: string): boolean {
+  return (
+    code === "delivery.forbiddenElement" ||
+    code === "delivery.unsupportedSecureDelivery" ||
+    code === "delivery.unsupportedAdaptiveResponseProcessing" ||
+    code === "adaptiveTurn.materialization.forbiddenElement" ||
+    code === "adaptiveTurn.materialization.unsupported"
+  );
+}
+
+function preparationDiagnosticCodeForLowerLevelCode(
+  code: string,
+  mode: QtiDeliveryPreparationMode,
+): string {
+  if (
+    code === "delivery.forbiddenElement" ||
+    code === "adaptiveTurn.materialization.forbiddenElement"
+  ) {
+    return "delivery.preparation.forbiddenElement";
+  }
+  if (code === "delivery.unsupportedAdaptiveResponseProcessing") {
+    return "delivery.preparation.unsupportedAdaptiveResponseProcessing";
+  }
+  return mode === "server-materialized-adaptive"
+    ? "delivery.preparation.unsupportedMaterialization"
+    : "delivery.preparation.unsupportedSecureDelivery";
+}

package/src/delivery-redaction.ts

@@ -167,7 +167,13 @@ export function redactDeliveryXml(
     [parsed.root, ...descendants(parsed.root, () => true)],
     (node, normalizedName) => policy.isForbiddenElement(node, normalizedName),
   );
-  const redactedXml = removeSourceRanges(xml, redactionRanges);
+  const redactedXml = applySourceRangeEdits(
+    xml,
+    redactionRanges.map((range) => ({
+      startOffset: range.startOffset,
+      endOffset: range.endOffset,
+    })),
+  );
   const redactedAnalysis = analyzeDeliveryXml(parseDeliveryXml(redactedXml), policy);
   if (!redactedAnalysis.deliverySafe || !redactedAnalysis.secureDeliverySupported) {
     return {
@@ -203,16 +209,36 @@ export function sourceRangeFor(node: XmlNode): RedactionRange[] {
   return [{ startOffset: node.sourceRange.startOffset, endOffset }];
 }
 
-export function removeSourceRanges(xml: string, ranges: readonly RedactionRange[]): string {
+export function applySourceRangeEdits(xml: string, edits: readonly SourceRangeEdit[]): string {
+  if (edits.length === 0) return xml;
+  const sorted = edits.toSorted((left, right) => left.startOffset - right.startOffset);
+  assertNonOverlappingSourceRangeEdits(sorted);
   let output = "";
   let cursor = 0;
-  for (const range of ranges) {
-    output += xml.slice(cursor, range.startOffset);
-    cursor = range.endOffset;
+  for (const edit of sorted) {
+    output += xml.slice(cursor, edit.startOffset);
+    if (edit.text !== undefined) output += edit.text;
+    cursor = edit.endOffset;
   }
   return output + xml.slice(cursor);
 }
 
+function assertNonOverlappingSourceRangeEdits(edits: readonly SourceRangeEdit[]): void {
+  for (let index = 1; index < edits.length; index += 1) {
+    const previous = edits[index - 1];
+    const current = edits[index];
+    if (!previous || !current || current.startOffset >= previous.endOffset) continue;
+    throw new Error("Source range edits must not overlap.");
+  }
+}
+
+export function removeSourceRanges(xml: string, ranges: readonly RedactionRange[]): string {
+  return applySourceRangeEdits(
+    xml,
+    ranges.map((range) => ({ startOffset: range.startOffset, endOffset: range.endOffset })),
+  );
+}
+
 export function normalizedQtiElementName(localName: string): string {
   const lower = localName.toLowerCase();
   return lower.startsWith("qti-") ? lower.slice("qti-".length) : lower;
@@ -240,8 +266,13 @@ export interface RedactionRange {
   endOffset: number;
 }
 
+export interface SourceRangeEdit extends RedactionRange {
+  /** When omitted, the source range is removed. When set, the range is replaced with this text. */
+  text?: string | undefined;
+}
+
 function mergeSourceRanges(ranges: readonly RedactionRange[]): RedactionRange[] {
-  const sorted = [...ranges].sort((left, right) => left.startOffset - right.startOffset);
+  const sorted = ranges.toSorted((left, right) => left.startOffset - right.startOffset);
   const merged: RedactionRange[] = [];
   for (const range of sorted) {
     const last = merged.at(-1);

package/src/delivery-security.ts

@@ -82,13 +82,13 @@ const staticDeliveryPolicy: DeliveryRedactionPolicy = {
 
     return null;
   },
-  diagnosticCodeForFinding,
+  diagnosticCodeForFinding: staticDiagnosticCodeForFinding,
   forbiddenElementMessage(node: XmlNode) {
     return `${node.name} exposes answer keys, scoring, mapping, feedback, or solution information during delivery.`;
   },
 };
 
-function diagnosticCodeForFinding(kind: QtiDeliverySecurityFindingKind): string {
+function staticDiagnosticCodeForFinding(kind: QtiDeliverySecurityFindingKind): string {
   if (kind === "forbidden-delivery-element") return "delivery.forbiddenElement";
   if (kind === "unsupported-adaptive-response-processing") {
     return "delivery.unsupportedAdaptiveResponseProcessing";

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   type QtiAdaptiveTurnResponseInput,
   type QtiAdaptiveTurnResult,
 } from "./adaptive-turn.js";
+export { assertNever } from "./assert-never.js";
 export {
   createCatalogSupportResolution,
   type QtiCatalogSupportResolution,
@@ -20,6 +21,20 @@ export {
   type QtiResolvedPhysicalCompanionMaterial,
 } from "./companion-materials-resolution.js";
 export { isResolvableAssetUrl } from "./asset-url.js";
+export {
+  materializeQtiItemSubmission,
+  type QtiItemSubmissionMaterializationInput,
+  type QtiItemSubmissionMaterializationResult,
+  type QtiItemSubmissionResponseInput,
+  type QtiItemSubmissionScoringDisposition,
+  type QtiVariableSnapshot,
+} from "./item-submission-materialization.js";
+export {
+  prepareQtiDeliveryXml,
+  type QtiDeliveryPreparationMode,
+  type QtiDeliveryPreparationOptions,
+  type QtiDeliveryPreparationResult,
+} from "./delivery-preparation.js";
 export {
   analyzeQtiDeliverySecurity,
   buildQtiDeliverySafeXml,
@@ -34,7 +49,27 @@ export {
   type QtiPackageXmlNode,
   type QtiPackageXmlTree,
 } from "./package-xml.js";
+export {
+  parseQtiPackage,
+  type QtiAssessmentTestItemRef,
+  type QtiAssessmentTestPackageModel,
+  type QtiManifestFile,
+  type QtiManifestResource,
+  type QtiPackageAsset,
+  type QtiPackageAssetSource,
+  type QtiPackageInflateContext,
+  type QtiPackageInflateRaw,
+  type QtiPackageItem,
+  type QtiPackageItemSource,
+  type QtiPackageParseOptions,
+  type QtiPackageParseResult,
+  type QtiPackageShape,
+  type QtiStandardAlignment,
+  type QtiTimingMetadata,
+} from "./qti-package.js";
+export { detectPackageMediaType } from "./qti-package-assets.js";
 export { parseQtiXml } from "./parser.js";
+export { numericTuple3, numericTuple4 } from "./parser-values.js";
 export { isConformanceParseDiagnostic } from "./parse-diagnostics.js";
 export {
   scoreQtiItemServerSide,
@@ -42,6 +77,38 @@ export {
   type QtiServerScoringResponseInput,
   type QtiServerScoringResult,
 } from "./server-scoring.js";
+export {
+  associationMaximumResponses,
+  choiceMatchLimitExceeded,
+  choiceMatchMaximum,
+  directedPairChoiceUseCount,
+  matchMaxDiagnostics,
+  maximumAllowedResponses,
+  maximumMediaPlays,
+  maximumResponseDiagnostic,
+  mediaPlayCount,
+  minimumMediaPlays,
+  minimumRequiredResponses,
+  orderSubsetLimitsActive,
+  parseUnlimitedMaximum,
+  requiredResponseDiagnostic,
+  responseCount,
+  responseIsEmpty,
+  responseLimitAttribute,
+  responseValidationPolicy,
+  wouldExceedChoiceMatchMaximum,
+  type DirectedPairUseSide,
+  type QtiResponseValidationPolicy,
+} from "./response-validation-policy.js";
+export {
+  validateQtiResponseVariables,
+  type QtiResponseValidationDiagnostic,
+  type QtiResponseValidationDiagnosticCode,
+  type QtiResponseValidationInput,
+  type QtiResponseValidationResult,
+  type QtiResponseVariableInput,
+  type QtiResponseVariablesInput,
+} from "./response-validation.js";
 export {
   serializeResponseProcessing,
   type QtiSerializeResponseProcessingResult,

package/src/item-scoring-expectation.ts

@@ -0,0 +1,9 @@
+import type { QtiAssessmentItem } from "./types.js";
+
+/** Items that declare automated scoring via response processing or a SCORE outcome. */
+export function itemExpectsAutomatedScore(item: QtiAssessmentItem): boolean {
+  return (
+    Boolean(item.responseProcessing) ||
+    item.outcomeDeclarations.some((declaration) => declaration.identifier === "SCORE")
+  );
+}