@longsightgroup/qti3-core 0.8.1 → 0.8.2

package/src/index.ts

@@ -5,6 +5,15 @@ export {
   type QtiResolvedCatalogReference,
   type QtiResolvedCatalogSupport,
 } from "./catalog.js";
+export {
+  createCompanionMaterialsResolution,
+  type QtiCompanionMaterialsResolution,
+  type QtiCompanionMaterialsResolutionOptions,
+  type QtiResolvedCompanionMaterialUnparsedChild,
+  type QtiResolvedDigitalCompanionMaterial,
+  type QtiResolvedPhysicalCompanionMaterial,
+} from "./companion-materials-resolution.js";
+export { isResolvableAssetUrl } from "./asset-url.js";
 export {
   analyzeQtiDeliverySecurity,
   buildQtiDeliverySafeXml,
@@ -20,6 +29,7 @@ export {
   type QtiPackageXmlTree,
 } from "./package-xml.js";
 export { parseQtiXml } from "./parser.js";
+export { isConformanceParseDiagnostic } from "./parse-diagnostics.js";
 export {
   scoreQtiItemServerSide,
   type QtiServerScoringInput,
@@ -179,6 +189,7 @@ export type {
   QtiCompanionMaterialsUnparsedChild,
   QtiContentNode,
   QtiCustomInteractionDefinition,
+  QtiDigitalMaterial,
   QtiInteractionMarkupDefinition,
   QtiDiagnostic,
   QtiDocument,

package/src/parse-diagnostics.ts

@@ -0,0 +1,28 @@
+/**
+ * Diagnostic codes emitted while parsing QTI XML, before validation runs.
+ * Conformance fixtures use this classifier to separate parse-time diagnostics
+ * from validation diagnostics in `parseQtiXml` results.
+ */
+const CONFORMANCE_PARSE_DIAGNOSTIC_CODES = new Set([
+  "xml.parse",
+  "xml.empty",
+  "qti.root",
+  "processing.unsupported",
+  "processing.response.forbidden",
+  "interaction.unsupported",
+  "interaction.deprecated",
+  "interaction.custom.markupInteraction",
+  "interaction.portableCustom.markupInteraction",
+  "interaction.portableCustom.child.duplicate",
+  "companionMaterials.child.unsupported",
+  "companionMaterials.digitalMaterial.fileHref.duplicate",
+  "companionMaterials.digitalMaterial.fileHref.missing",
+  "companionMaterials.digitalMaterial.fileHref.empty",
+  "companionMaterials.digitalMaterial.resourceIcon.duplicate",
+  "companionMaterials.physicalMaterial.empty",
+  "item.child.duplicate",
+]);
+
+export function isConformanceParseDiagnostic(code: string): boolean {
+  return CONFORMANCE_PARSE_DIAGNOSTIC_CODES.has(code);
+}

package/src/parser-item-metadata.ts

@@ -9,10 +9,16 @@ import type {
   QtiCompanionMaterialsUnparsedChild,
   QtiContentNode,
   QtiDiagnostic,
+  QtiDigitalMaterial,
   QtiModalFeedback,
   QtiPhysicalMaterial,
   QtiStylesheet,
 } from "./types.js";
+import {
+  PARSED_COMPANION_MATERIAL_CHILD_NAMES,
+  type ParsedCompanionMaterialChildQtiName,
+  pushCompanionMaterialParseWarning,
+} from "./companion-materials.js";
 import { childElements, descendants, textContent, type XmlNode } from "./xml.js";
 
 export function firstChildElement(
@@ -146,12 +152,23 @@ export function parseCompanionMaterialsInfo(
   if (!node) return undefined;
 
   const physicalMaterials: QtiPhysicalMaterial[] = [];
+  const digitalMaterials: QtiDigitalMaterial[] = [];
   const unparsedChildren: QtiCompanionMaterialsUnparsedChild[] = [];
 
-  for (const child of childElements(node)) {
-    if (child.localName === "qti-physical-material") {
+  const companionMaterialHandlers = {
+    "qti-physical-material": (child) => {
       const material = parsePhysicalMaterial(child, diagnostics);
       if (material) physicalMaterials.push(material);
+    },
+    "qti-digital-material": (child) => {
+      const material = parseDigitalMaterial(child, diagnostics);
+      if (material) digitalMaterials.push(material);
+    },
+  } satisfies Record<ParsedCompanionMaterialChildQtiName, (child: XmlNode) => void>;
+
+  for (const child of childElements(node)) {
+    if (isParsedCompanionMaterialChildQtiName(child.localName)) {
+      companionMaterialHandlers[child.localName](child);
       continue;
     }
 
@@ -167,6 +184,7 @@ export function parseCompanionMaterialsInfo(
 
   return {
     physicalMaterials,
+    digitalMaterials,
     unparsedChildren,
     source: node.source,
   };
@@ -178,17 +196,68 @@ function parsePhysicalMaterial(
 ): QtiPhysicalMaterial | undefined {
   const text = textContent(node).trim();
   if (text.length === 0) {
-    diagnostics.push({
-      code: "companionMaterials.physicalMaterial.empty",
-      severity: "warning",
-      message: "qti-physical-material requires non-empty text content.",
-      path: node.source?.path,
-      source: node.source,
-    });
-    return undefined;
+    return pushCompanionMaterialParseWarning(
+      diagnostics,
+      "companionMaterials.physicalMaterial.empty",
+      "qti-physical-material requires non-empty text content.",
+      node.source?.path,
+      node.source,
+    );
   }
   return {
     text,
     source: node.source,
   };
 }
+
+function parseDigitalMaterial(
+  node: XmlNode,
+  diagnostics: QtiDiagnostic[],
+): QtiDigitalMaterial | undefined {
+  const fileHrefNode = firstChildElement(
+    node,
+    "qti-file-href",
+    diagnostics,
+    "companionMaterials.digitalMaterial.fileHref.duplicate",
+  );
+  if (!fileHrefNode) {
+    return pushCompanionMaterialParseWarning(
+      diagnostics,
+      "companionMaterials.digitalMaterial.fileHref.missing",
+      "qti-digital-material requires a qti-file-href child.",
+      node.source?.path,
+      node.source,
+    );
+  }
+
+  const fileHref = textContent(fileHrefNode).trim();
+  if (fileHref.length === 0) {
+    return pushCompanionMaterialParseWarning(
+      diagnostics,
+      "companionMaterials.digitalMaterial.fileHref.empty",
+      "qti-digital-material qti-file-href requires non-empty text content.",
+      fileHrefNode.source?.path,
+      fileHrefNode.source,
+    );
+  }
+
+  const resourceIconNode = firstChildElement(
+    node,
+    "qti-resource-icon",
+    diagnostics,
+    "companionMaterials.digitalMaterial.resourceIcon.duplicate",
+  );
+  const resourceIcon = resourceIconNode ? textContent(resourceIconNode).trim() : "";
+  return {
+    fileHref,
+    resourceIcon: resourceIcon.length > 0 ? resourceIcon : undefined,
+    attributes: node.attributes,
+    source: node.source,
+  };
+}
+
+function isParsedCompanionMaterialChildQtiName(
+  localName: string,
+): localName is ParsedCompanionMaterialChildQtiName {
+  return PARSED_COMPANION_MATERIAL_CHILD_NAMES.has(localName);
+}

package/src/support.ts

@@ -255,7 +255,7 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
       "packages/core/src/parser-item-metadata.test.ts",
     ],
     notes:
-      "Parses qti-physical-material text only. qti-digital-material is preserved in unparsedChildren and emits companionMaterials.child.unsupported at parse time.",
+      "Parses qti-physical-material text and qti-digital-material file references. Digital materials require non-empty qti-file-href text and may include label, mime-type, and qti-resource-icon metadata. Hosts read resolved materials through createCompanionMaterialsResolution() or player.getCompanionMaterialsResolution().",
   },
   {
     qtiName: "qti-physical-material",
@@ -277,10 +277,10 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
   {
     qtiName: "qti-digital-material",
     category: "itemMetadata",
-    support: "unsupported",
+    support: "parsed",
     specReference: "QTI 3.0.1 ASI",
-    parse: false,
-    validate: false,
+    parse: true,
+    validate: true,
     render: false,
     process: false,
     fixtures: [
@@ -291,7 +291,7 @@ export const itemMetadataSupport: QtiItemMetadataElementSupport[] = [
       "packages/core/src/parser-item-metadata.test.ts",
     ],
     notes:
-      "Recognized as an unparsed child of qti-companion-materials-info. Full digital material parsing is not implemented yet.",
+      "Child of qti-companion-materials-info. Parsed from qti-file-href with optional label, mime-type, and qti-resource-icon metadata. Element attributes are preserved on the parsed model. Missing or empty qti-file-href emits companionMaterials.digitalMaterial.fileHref.* diagnostics.",
   },
 ];
 

package/src/types.ts

@@ -456,6 +456,7 @@ export interface QtiAssessmentItem {
 
 export interface QtiCompanionMaterialsInfo {
   physicalMaterials: QtiPhysicalMaterial[];
+  digitalMaterials: QtiDigitalMaterial[];
   unparsedChildren: QtiCompanionMaterialsUnparsedChild[];
   source?: QtiSourceLocation | undefined;
 }
@@ -470,6 +471,13 @@ export interface QtiPhysicalMaterial {
   source?: QtiSourceLocation | undefined;
 }
 
+export interface QtiDigitalMaterial {
+  fileHref: string;
+  resourceIcon?: string | undefined;
+  attributes: Record<string, string>;
+  source?: QtiSourceLocation | undefined;
+}
+
 export interface QtiModalFeedback {
   identifier: string;
   outcomeIdentifier: string;

package/src/validation-companion-materials.ts

@@ -0,0 +1,48 @@
+import type { QtiAssessmentItem, QtiDiagnostic } from "./types.js";
+import { PARSED_COMPANION_MATERIAL_CHILD_NAMES } from "./companion-materials.js";
+
+export function validateCompanionMaterials(
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  const companionMaterials = item.companionMaterials;
+  if (!companionMaterials) return;
+
+  for (const child of companionMaterials.unparsedChildren) {
+    if (!PARSED_COMPANION_MATERIAL_CHILD_NAMES.has(child.qtiName)) continue;
+
+    diagnostics.push({
+      code: "companionMaterials.model.inconsistent",
+      severity: "error",
+      message: `${child.qtiName} must be represented in the parsed companion materials model, not as an unparsed child.`,
+      path: child.source?.path,
+      source: child.source,
+    });
+  }
+
+  for (const material of companionMaterials.physicalMaterials) {
+    if (material.text.trim().length === 0) {
+      diagnostics.push({
+        code: "companionMaterials.physicalMaterial.empty.model",
+        severity: "error",
+        message:
+          "qti-physical-material requires non-empty text content in the parsed companion materials model.",
+        path: material.source?.path,
+        source: material.source,
+      });
+    }
+  }
+
+  for (const material of companionMaterials.digitalMaterials) {
+    if (material.fileHref.trim().length === 0) {
+      diagnostics.push({
+        code: "companionMaterials.digitalMaterial.fileHref.empty.model",
+        severity: "error",
+        message:
+          "qti-digital-material requires non-empty qti-file-href text content in the parsed companion materials model.",
+        path: material.source?.path,
+        source: material.source,
+      });
+    }
+  }
+}

package/src/validation.ts

@@ -25,6 +25,7 @@ import { validateInteractionSharedVocabulary } from "./shared-vocabulary-interac
 import { isValidQtiPatternMask } from "./pattern-mask.js";
 import { validateQtiDataSsmlMetadata } from "./tts.js";
 import { qtiValueToStringList } from "./value-format.js";
+import { validateCompanionMaterials } from "./validation-companion-materials.js";
 
 const BUILT_IN_COMPLETION_STATUS = "completionStatus";
 
@@ -713,37 +714,6 @@ function validateOutcomeLookupTables(item: QtiAssessmentItem, diagnostics: QtiDi
   }
 }
 
-function validateCompanionMaterials(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
-  const companionMaterials = item.companionMaterials;
-  if (!companionMaterials) return;
-
-  for (const child of companionMaterials.unparsedChildren) {
-    if (child.qtiName === "qti-physical-material") {
-      diagnostics.push({
-        code: "companionMaterials.model.inconsistent",
-        severity: "error",
-        message:
-          "Empty qti-physical-material must be represented as a parse warning, not an unparsed child.",
-        path: child.source?.path,
-        source: child.source,
-      });
-    }
-  }
-
-  for (const material of companionMaterials.physicalMaterials) {
-    if (material.text.trim().length === 0) {
-      diagnostics.push({
-        code: "companionMaterials.physicalMaterial.empty.model",
-        severity: "error",
-        message:
-          "qti-physical-material requires non-empty text content in the parsed companion materials model.",
-        path: material.source?.path,
-        source: material.source,
-      });
-    }
-  }
-}
-
 function validateStylesheets(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
   for (const stylesheet of item.stylesheets) {
     if (stylesheet.href.trim().length > 0) continue;