@longsightgroup/qti3-core 0.9.0 → 0.9.2

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].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 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,
+  };
+}

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,9 @@
+export {
+  processQtiAdaptiveItemTurn,
+  type QtiAdaptiveTurnInput,
+  type QtiAdaptiveTurnResponseInput,
+  type QtiAdaptiveTurnResult,
+} from "./adaptive-turn.js";
 export {
   createCatalogSupportResolution,
   type QtiCatalogSupportResolution,
@@ -227,6 +233,7 @@ export type {
   QtiResponseProcessing,
   QtiResponseRule,
   QtiScoreResult,
+  QtiStylesheet,
   QtiLookupOutcomeValue,
   QtiSetOutcomeValue,
   QtiSupportStatus,