@longsightgroup/qti3-core 0.9.1 → 0.9.3

package/src/delivery-security.ts

@@ -1,13 +1,25 @@
-import type { QtiDiagnostic, QtiSourceLocation } from "./types.js";
-import { descendants, parseXmlTree, type XmlNode } from "./xml.js";
+import {
+  FORBIDDEN_DELIVERY_SECRET_ELEMENT_NAMES,
+  analyzeDeliveryXml,
+  isDeclarationDefaultValue,
+  normalizedQtiElementName,
+  parseDeliveryXml,
+  parseXmlBoolean,
+  redactDeliveryXml,
+  type DeliveryRedactionPolicy,
+  type QtiDeliverySecurityAnalysis,
+  type QtiDeliverySecurityFindingKind,
+} from "./delivery-redaction.js";
+import type { XmlNode } from "./xml.js";
+
+export type {
+  QtiDeliverySecurityAnalysis,
+  QtiDeliverySecurityFinding,
+  QtiDeliverySecurityFindingKind,
+} from "./delivery-redaction.js";
 
 const FORBIDDEN_DELIVERY_ELEMENT_NAMES = new Set([
-  "correct-response",
-  "mapping",
-  "area-mapping",
-  "match-table",
-  "interpolation-table",
-  "response-processing",
+  ...FORBIDDEN_DELIVERY_SECRET_ELEMENT_NAMES,
   "feedback-inline",
   "feedback-block",
   "modal-feedback",
@@ -18,222 +30,63 @@ const UNSUPPORTED_SECURE_DELIVERY_ELEMENT_NAMES = new Set([
   "set-correct-response",
 ]);
 
-const DEFAULT_VALUE_DECLARATION_ELEMENT_NAMES = new Set([
-  "response-declaration",
-  "outcome-declaration",
-  "template-declaration",
-]);
-
-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 QtiDeliverySafeXmlResult {
   ok: boolean;
-  diagnostics: QtiDiagnostic[];
+  diagnostics: QtiDeliverySecurityAnalysis["diagnostics"];
   analysis: QtiDeliverySecurityAnalysis;
   xml?: string | undefined;
 }
 
 export function analyzeQtiDeliverySecurity(xml: string): QtiDeliverySecurityAnalysis {
-  const parsed = parseDeliveryXml(xml);
-  return analyzeParsedDeliveryXml(parsed);
+  return analyzeDeliveryXml(parseDeliveryXml(xml), staticDeliveryPolicy);
 }
 
-function analyzeParsedDeliveryXml(parsed: {
-  root: XmlNode | undefined;
-  diagnostics: QtiDiagnostic[];
-}): 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 (isForbiddenDeliveryElement(node, normalizedName)) {
-        findings.push({
-          kind: "forbidden-delivery-element",
-          qtiName: node.name,
-          localName: node.localName,
-          message: `${node.name} exposes answer keys, scoring, mapping, feedback, or solution information during delivery.`,
-          source: node.source,
-        });
-      }
-      if (UNSUPPORTED_SECURE_DELIVERY_ELEMENT_NAMES.has(normalizedName)) {
-        findings.push({
-          kind: "unsupported-secure-delivery-element",
-          qtiName: node.name,
-          localName: node.localName,
-          message: `${node.name} is not supported by secure delivery redaction v1.`,
-          source: node.source,
-        });
-      }
+export function buildQtiDeliverySafeXml(xml: string): QtiDeliverySafeXmlResult {
+  return redactDeliveryXml(xml, staticDeliveryPolicy);
+}
+
+const staticDeliveryPolicy: DeliveryRedactionPolicy = {
+  isForbiddenElement(node, normalizedName) {
+    return (
+      FORBIDDEN_DELIVERY_ELEMENT_NAMES.has(normalizedName) ||
+      isDeclarationDefaultValue(node, normalizedName)
+    );
+  },
+  unsupportedFinding(node, normalizedName, nodes) {
+    if (UNSUPPORTED_SECURE_DELIVERY_ELEMENT_NAMES.has(normalizedName)) {
+      return {
+        kind: "unsupported-secure-delivery-element",
+        qtiName: node.name,
+        localName: node.localName,
+        message: `${node.name} is not supported by secure delivery redaction v1.`,
+        source: node.source,
+      };
     }
 
     if (
-      parseXmlBoolean(parsed.root.attributes.adaptive) === true &&
-      nodes.some((node) => normalizedQtiElementName(node.localName) === "response-processing")
+      node.parent === undefined &&
+      parseXmlBoolean(node.attributes.adaptive) === true &&
+      nodes.some(
+        (candidate) => normalizedQtiElementName(candidate.localName) === "response-processing",
+      )
     ) {
-      findings.push({
+      return {
         kind: "unsupported-adaptive-response-processing",
-        qtiName: parsed.root.name,
-        localName: parsed.root.localName,
+        qtiName: node.name,
+        localName: node.localName,
         message:
           "Adaptive response processing requires server-side item materialization before secure delivery.",
-        source: parsed.root.source,
-      });
+        source: node.source,
+      };
     }
-  }
-
-  diagnostics.push(...findings.map(findingToDiagnostic));
-  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 buildQtiDeliverySafeXml(xml: string): QtiDeliverySafeXmlResult {
-  const parsed = parseDeliveryXml(xml);
-  const analysis = analyzeParsedDeliveryXml(parsed);
-  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),
-  ]);
-  const redactedXml = removeSourceRanges(xml, redactionRanges);
-  const redactedAnalysis = analyzeQtiDeliverySecurity(redactedXml);
-  if (!redactedAnalysis.deliverySafe) {
-    return {
-      ok: false,
-      diagnostics: [...analysis.diagnostics, ...redactedAnalysis.diagnostics],
-      analysis: redactedAnalysis,
-    };
-  }
-
-  return {
-    ok: true,
-    xml: redactedXml,
-    diagnostics: redactedAnalysis.diagnostics,
-    analysis: redactedAnalysis,
-  };
-}
-
-function parseDeliveryXml(xml: string): {
-  root: XmlNode | undefined;
-  diagnostics: QtiDiagnostic[];
-} {
-  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 };
-}
-
-function normalizedQtiElementName(localName: string): string {
-  const lower = localName.toLowerCase();
-  return lower.startsWith("qti-") ? lower.slice("qti-".length) : lower;
-}
-
-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;
-}
-
-function isForbiddenDeliveryElement(
-  node: XmlNode,
-  normalizedName = normalizedQtiElementName(node.localName),
-): boolean {
-  if (FORBIDDEN_DELIVERY_ELEMENT_NAMES.has(normalizedName)) return true;
-  return (
-    normalizedName === "default-value" &&
-    DEFAULT_VALUE_DECLARATION_ELEMENT_NAMES.has(
-      normalizedQtiElementName(node.parent?.localName ?? ""),
-    )
-  );
-}
-
-function findingToDiagnostic(finding: QtiDeliverySecurityFinding): QtiDiagnostic {
-  const code = diagnosticCodeForFinding(finding.kind);
-  return {
-    code,
-    severity: "error",
-    message: finding.message,
-    path: finding.source?.path,
-    source: finding.source,
-  };
-}
+    return null;
+  },
+  diagnosticCodeForFinding,
+  forbiddenElementMessage(node: XmlNode) {
+    return `${node.name} exposes answer keys, scoring, mapping, feedback, or solution information during delivery.`;
+  },
+};
 
 function diagnosticCodeForFinding(kind: QtiDeliverySecurityFindingKind): string {
   if (kind === "forbidden-delivery-element") return "delivery.forbiddenElement";
@@ -242,42 +95,3 @@ function diagnosticCodeForFinding(kind: QtiDeliverySecurityFindingKind): string
   }
   return "delivery.unsupportedSecureDelivery";
 }
-
-interface RedactionRange {
-  startOffset: number;
-  endOffset: number;
-}
-
-function readRedactionRanges(nodes: XmlNode[]): RedactionRange[] {
-  const ranges = nodes.flatMap((node) => {
-    if (!isForbiddenDeliveryElement(node)) return [];
-    const endOffset = node.sourceRange.endOffset;
-    if (node.sourceRange.startOffset < 0 || endOffset === undefined) return [];
-    return [{ startOffset: node.sourceRange.startOffset, endOffset }];
-  });
-  return mergeSourceRanges(ranges);
-}
-
-function mergeSourceRanges(ranges: RedactionRange[]): RedactionRange[] {
-  const sorted = [...ranges].sort((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 removeSourceRanges(xml: string, ranges: 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);
-}

package/src/index.ts

@@ -1,3 +1,10 @@
+export {
+  processQtiAdaptiveItemTurn,
+  type QtiAdaptiveTurnInput,
+  type QtiAdaptiveTurnResponseInput,
+  type QtiAdaptiveTurnResult,
+} from "./adaptive-turn.js";
+export { assertNever } from "./assert-never.js";
 export {
   createCatalogSupportResolution,
   type QtiCatalogSupportResolution,
@@ -29,6 +36,7 @@ export {
   type QtiPackageXmlTree,
 } from "./package-xml.js";
 export { parseQtiXml } from "./parser.js";
+export { numericTuple3, numericTuple4 } from "./parser-values.js";
 export { isConformanceParseDiagnostic } from "./parse-diagnostics.js";
 export {
   scoreQtiItemServerSide,
@@ -227,6 +235,7 @@ export type {
   QtiResponseProcessing,
   QtiResponseRule,
   QtiScoreResult,
+  QtiStylesheet,
   QtiLookupOutcomeValue,
   QtiSetOutcomeValue,
   QtiSupportStatus,

package/src/parser-custom-interactions.ts

@@ -212,7 +212,7 @@ function parseCustomMarkupNode(
       code: options.nestedInteractionCode,
       severity: "error",
       message: `${options.contextName} must not contain nested QTI interaction ${node.localName}.`,
-      path: node.source?.path,
+      path: node.source.path,
       source: node.source,
     });
   }

package/src/parser-declarations.ts

@@ -1,6 +1,7 @@
 import {
   coerceValue,
   normalizeValueForCardinality,
+  parseBaseType,
   parseCardinality,
   parseCoords,
   parseShape,
@@ -18,7 +19,7 @@ import { childElements, textContent, type XmlNode } from "./xml.js";
 
 export function parseResponseDeclaration(node: XmlNode): QtiResponseDeclaration {
   const cardinality = parseCardinality(node.attributes.cardinality);
-  const baseType = node.attributes["base-type"] as QtiResponseDeclaration["baseType"];
+  const baseType = parseBaseType(node.attributes["base-type"]);
   return {
     kind: "response",
     identifier: node.attributes.identifier ?? "",
@@ -37,7 +38,7 @@ export function parseResponseDeclaration(node: XmlNode): QtiResponseDeclaration
 }
 
 export function parseOutcomeDeclaration(node: XmlNode): QtiOutcomeDeclaration {
-  const baseType = node.attributes["base-type"] as QtiOutcomeDeclaration["baseType"];
+  const baseType = parseBaseType(node.attributes["base-type"]);
   return {
     kind: "outcome",
     identifier: node.attributes.identifier ?? "",
@@ -51,7 +52,7 @@ export function parseOutcomeDeclaration(node: XmlNode): QtiOutcomeDeclaration {
 }
 
 export function parseTemplateDeclaration(node: XmlNode): QtiTemplateDeclaration {
-  const baseType = node.attributes["base-type"] as QtiTemplateDeclaration["baseType"];
+  const baseType = parseBaseType(node.attributes["base-type"]);
   return {
     kind: "template",
     identifier: node.attributes.identifier ?? "",

package/src/parser-item-metadata.ts

@@ -28,13 +28,14 @@ export function firstChildElement(
   duplicateCode: string,
 ): XmlNode | undefined {
   const matches = childElements(parent, childName);
-  if (matches.length > 1) {
+  const duplicate = matches[1];
+  if (duplicate) {
     diagnostics.push({
       code: duplicateCode,
       severity: "error",
       message: `${parent.localName} allows at most one ${childName} child.`,
-      path: matches[1]?.source?.path ?? parent.source?.path,
-      source: matches[1]?.source ?? parent.source,
+      path: duplicate.source.path,
+      source: duplicate.source,
     });
   }
   return matches[0];
@@ -177,7 +178,7 @@ export function parseCompanionMaterialsInfo(
       code: "companionMaterials.child.unsupported",
       severity: "warning",
       message: `${child.localName} is not currently modeled in companion materials parsing.`,
-      path: child.source?.path,
+      path: child.source.path,
       source: child.source,
     });
   }
@@ -200,7 +201,7 @@ function parsePhysicalMaterial(
       diagnostics,
       "companionMaterials.physicalMaterial.empty",
       "qti-physical-material requires non-empty text content.",
-      node.source?.path,
+      node.source.path,
       node.source,
     );
   }
@@ -225,7 +226,7 @@ function parseDigitalMaterial(
       diagnostics,
       "companionMaterials.digitalMaterial.fileHref.missing",
       "qti-digital-material requires a qti-file-href child.",
-      node.source?.path,
+      node.source.path,
       node.source,
     );
   }
@@ -236,7 +237,7 @@ function parseDigitalMaterial(
       diagnostics,
       "companionMaterials.digitalMaterial.fileHref.empty",
       "qti-digital-material qti-file-href requires non-empty text content.",
-      fileHrefNode.source?.path,
+      fileHrefNode.source.path,
       fileHrefNode.source,
     );
   }

package/src/parser-processing.ts

@@ -672,8 +672,8 @@ function parseExpression(node: XmlNode): QtiProcessingExpression | undefined {
     if (variable && correct) {
       return {
         type: "matchCorrect",
-        identifier: variable?.attributes.identifier ?? "",
-        correctIdentifier: correct?.attributes.identifier ?? "",
+        identifier: variable.attributes.identifier ?? "",
+        correctIdentifier: correct.attributes.identifier ?? "",
         source: node.source,
       };
     }

package/src/parser-values.ts

@@ -1,4 +1,5 @@
 import type {
+  QtiBaseType,
   QtiCardinality,
   QtiRecordValue,
   QtiResponseDeclaration,
@@ -6,6 +7,41 @@ import type {
   QtiValue,
 } from "./types.js";
 
+const QTI_BASE_TYPES = new Set<string>([
+  "identifier",
+  "boolean",
+  "integer",
+  "float",
+  "string",
+  "point",
+  "pair",
+  "directedPair",
+  "duration",
+  "file",
+  "uri",
+]);
+
+export function isQtiBaseType(value: string): value is QtiBaseType {
+  return QTI_BASE_TYPES.has(value);
+}
+
+export function parseBaseType(value: string | undefined): QtiBaseType | undefined {
+  if (value === undefined) return undefined;
+  return isQtiBaseType(value) ? value : undefined;
+}
+
+export function numericTuple3(values: number[]): [number, number, number] | undefined {
+  const [a, b, c] = values;
+  if (a === undefined || b === undefined || c === undefined) return undefined;
+  return [a, b, c];
+}
+
+export function numericTuple4(values: number[]): [number, number, number, number] | undefined {
+  const [a, b, c, d] = values;
+  if (a === undefined || b === undefined || c === undefined || d === undefined) return undefined;
+  return [a, b, c, d];
+}
+
 export function coerceValue(value: string, baseType: string | undefined): QtiScalarValue {
   if (baseType === "integer") return Number.parseInt(value, 10);
   if (baseType === "float") return Number.parseFloat(value);

package/src/processing-evaluator-boolean.ts

@@ -0,0 +1,48 @@
+import type { QtiProcessingExpression, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { booleanValueOrNull } from "./processing-values.js";
+
+type BooleanExpression = Extract<QtiProcessingExpression, { type: "and" | "anyN" | "or" | "not" }>;
+
+export function evaluateBooleanExpression(
+  expression: BooleanExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "and": {
+      let sawNull = false;
+      for (const item of expression.expressions) {
+        const value = booleanValueOrNull(context.evaluate(item));
+        if (value === false) return false;
+        if (value === null) sawNull = true;
+      }
+      return sawNull ? null : true;
+    }
+    case "anyN": {
+      const min = context.indexValue(expression.min) ?? 0;
+      const max = context.indexValue(expression.max) ?? 0;
+      const values = expression.expressions.map((item) => context.evaluate(item));
+      const trueCount = values.filter((value) => value === true).length;
+      const nullCount = values.filter((value) => value === null).length;
+      if (min > max || trueCount > max || trueCount + nullCount < min) return false;
+      if (trueCount >= min && trueCount <= max) return true;
+      return null;
+    }
+    case "or": {
+      let sawNull = false;
+      for (const item of expression.expressions) {
+        const value = booleanValueOrNull(context.evaluate(item));
+        if (value === true) return true;
+        if (value === null) sawNull = true;
+      }
+      return sawNull ? null : false;
+    }
+    case "not": {
+      const value = booleanValueOrNull(context.evaluate(expression.expression));
+      return value === null ? null : !value;
+    }
+    default:
+      return assertNever(expression);
+  }
+}

package/src/processing-evaluator-collection.ts

@@ -0,0 +1,50 @@
+import type { QtiProcessingExpression, QtiScalarValue, QtiValue } from "./types.js";
+import { assertNever } from "./assert-never.js";
+import type { EvaluationContext } from "./processing-evaluator.js";
+import { valueContainer } from "./processing-values.js";
+
+type CollectionExpression = Extract<
+  QtiProcessingExpression,
+  { type: "multiple" | "ordered" | "index" | "containerSize" }
+>;
+type RepeatExpression = Extract<QtiProcessingExpression, { type: "repeat" }>;
+
+export function evaluateCollectionExpression(
+  expression: CollectionExpression,
+  context: EvaluationContext,
+): QtiValue {
+  switch (expression.type) {
+    case "multiple":
+    case "ordered": {
+      const values = expression.expressions.flatMap((item) =>
+        valueContainer(context.evaluate(item)),
+      );
+      return values.length > 0 ? values : null;
+    }
+    case "index": {
+      const values = valueContainer(context.evaluate(expression.expression));
+      const n = context.indexValue(expression.n);
+      if (n === undefined || n < 1 || n > values.length) return null;
+      return values[n - 1] ?? null;
+    }
+    case "containerSize":
+      return valueContainer(context.evaluate(expression.expression)).length;
+    default:
+      return assertNever(expression);
+  }
+}
+
+export function evaluateRepeatExpression(
+  expression: RepeatExpression,
+  context: EvaluationContext,
+): QtiValue {
+  const repeats = context.indexValue(expression.numberRepeats);
+  if (repeats === undefined || repeats < 1) return null;
+  const container: QtiScalarValue[] = [];
+  for (let repeat = 0; repeat < repeats; repeat += 1) {
+    for (const item of expression.expressions) {
+      container.push(...valueContainer(context.evaluate(item)));
+    }
+  }
+  return container.length > 0 ? container : null;
+}