@conform-ed/qti-xml 0.0.16

package/src/serialize-result.ts

@@ -0,0 +1,215 @@
+/**
+ * QTI Results Reporting XML serialization — conform-ed's first XML writer. Takes the
+ * normalized/contracts document shape and emits an instance against the official
+ * binding (namespace imsqti_result_v3p0), in the XSD's element order. The export
+ * conformance gate: "The system MUST create an instance with all of the REQUIRED
+ * properties and values; … The XML instance MUST be valid with respect to the
+ * official XSD" — guarded in tests by round-tripping the output through our own
+ * parser, normalizer, and strict contracts schema.
+ */
+
+import type {
+  QtiAssessmentResultDocument,
+  QtiResultContextVariable,
+  QtiResultItemResult,
+  QtiResultOutcomeVariable,
+  QtiResultResponseVariable,
+  QtiResultSupport,
+  QtiResultTemplateVariable,
+  QtiResultTestResult,
+  QtiResultValue,
+} from "@conform-ed/contracts/qti/v3_0_1";
+
+import { XmlWriter, type AttributeValue } from "./xml-writer";
+
+const resultNamespace = "http://www.imsglobal.org/xsd/imsqti_result_v3p0";
+const resultSchemaLocation = `${resultNamespace} https://purl.imsglobal.org/spec/qti/v3p0/schema/xsd/imsqti_resultv3p0_v1p0.xsd`;
+
+function writeValues(writer: XmlWriter, values: readonly QtiResultValue[] | undefined): void {
+  for (const entry of values ?? []) {
+    writer.element(
+      "value",
+      [
+        ["fieldIdentifier", entry.fieldIdentifier],
+        ["baseType", entry.baseType],
+      ],
+      entry.value,
+    );
+  }
+}
+
+function writeResponseVariable(writer: XmlWriter, variable: QtiResultResponseVariable): void {
+  writer.element(
+    "responseVariable",
+    [
+      ["identifier", variable.identifier],
+      ["cardinality", variable.cardinality],
+      ["baseType", variable.baseType],
+      ["choiceSequence", variable.choiceSequence?.join(" ")],
+      ["scoreStatus", variable.scoreStatus],
+      ["answeredStatus", variable.answeredStatus],
+    ],
+    () => {
+      if (variable.correctResponse) {
+        writer.element("correctResponse", [["interpretation", variable.correctResponse.interpretation]], () => {
+          writeValues(writer, variable.correctResponse?.values);
+        });
+      }
+
+      writer.element("candidateResponse", [], () => {
+        writeValues(writer, variable.candidateResponse.values);
+      });
+    },
+  );
+}
+
+function writeOutcomeVariable(writer: XmlWriter, variable: QtiResultOutcomeVariable): void {
+  const attributes: ReadonlyArray<readonly [string, AttributeValue]> = [
+    ["identifier", variable.identifier],
+    ["cardinality", variable.cardinality],
+    ["baseType", variable.baseType],
+    ["view", variable.view?.join(" ")],
+    ["interpretation", variable.interpretation],
+    ["longInterpretation", variable.longInterpretation],
+    ["normalMaximum", variable.normalMaximum],
+    ["normalMinimum", variable.normalMinimum],
+    ["masteryValue", variable.masteryValue],
+    ["external-scored", variable.externalScored],
+    ["variable-identifier-ref", variable.variableIdentifierRef],
+  ];
+
+  if (!variable.values?.length) {
+    writer.element("outcomeVariable", attributes);
+    return;
+  }
+
+  writer.element("outcomeVariable", attributes, () => {
+    writeValues(writer, variable.values);
+  });
+}
+
+function writeContextTemplateVariable(
+  writer: XmlWriter,
+  name: "templateVariable" | "contextVariable",
+  variable: QtiResultTemplateVariable | QtiResultContextVariable,
+): void {
+  const attributes: ReadonlyArray<readonly [string, AttributeValue]> = [
+    ["identifier", variable.identifier],
+    ["cardinality", variable.cardinality],
+    ["baseType", variable.baseType],
+  ];
+
+  if (!variable.values?.length) {
+    writer.element(name, attributes);
+    return;
+  }
+
+  writer.element(name, attributes, () => {
+    writeValues(writer, variable.values);
+  });
+}
+
+function writeSupport(writer: XmlWriter, support: QtiResultSupport): void {
+  writer.element("support", [
+    ["name", support.name],
+    ["assignment", support.assignment],
+    ["value", support.value],
+    ["language", support.xmlLang],
+  ]);
+}
+
+function writeVariables(writer: XmlWriter, container: QtiResultTestResult | QtiResultItemResult): void {
+  for (const variable of container.responseVariables ?? []) {
+    writeResponseVariable(writer, variable);
+  }
+
+  for (const variable of container.templateVariables ?? []) {
+    writeContextTemplateVariable(writer, "templateVariable", variable);
+  }
+
+  for (const variable of container.outcomeVariables ?? []) {
+    writeOutcomeVariable(writer, variable);
+  }
+
+  for (const variable of container.contextVariables ?? []) {
+    writeContextTemplateVariable(writer, "contextVariable", variable);
+  }
+}
+
+/** Serialize a results document against the official 3.0 binding. */
+export function serializeQtiAssessmentResult(document: QtiAssessmentResultDocument): string {
+  const { assessmentResult } = document;
+  const writer = new XmlWriter();
+
+  writer.line('<?xml version="1.0" encoding="UTF-8"?>');
+  writer.element(
+    "assessmentResult",
+    [
+      ["xmlns", resultNamespace],
+      ["xmlns:xsi", "http://www.w3.org/2001/XMLSchema-instance"],
+      ["xsi:schemaLocation", resultSchemaLocation],
+    ],
+    () => {
+      const { context } = assessmentResult;
+
+      if (context.sessionIdentifiers?.length) {
+        writer.element("context", [["sourcedId", context.sourcedId]], () => {
+          for (const session of context.sessionIdentifiers ?? []) {
+            // The binding spells the attribute sourceID.
+            writer.element("sessionIdentifier", [
+              ["sourceID", session.sourceId],
+              ["identifier", session.identifier],
+            ]);
+          }
+        });
+      } else {
+        writer.element("context", [["sourcedId", context.sourcedId]]);
+      }
+
+      const { testResult } = assessmentResult;
+
+      if (testResult) {
+        writer.element(
+          "testResult",
+          [
+            ["identifier", testResult.identifier],
+            ["datestamp", testResult.datestamp],
+          ],
+          () => {
+            writeVariables(writer, testResult);
+
+            for (const support of testResult.supports ?? []) {
+              writeSupport(writer, support);
+            }
+          },
+        );
+      }
+
+      for (const itemResult of assessmentResult.itemResults ?? []) {
+        writer.element(
+          "itemResult",
+          [
+            ["identifier", itemResult.identifier],
+            ["sequenceIndex", itemResult.sequenceIndex],
+            ["datestamp", itemResult.datestamp],
+            ["sessionStatus", itemResult.sessionStatus],
+          ],
+          () => {
+            writeVariables(writer, itemResult);
+
+            // The XSD sequence puts candidateComment after the variables.
+            if (itemResult.candidateComment !== undefined) {
+              writer.element("candidateComment", [], itemResult.candidateComment);
+            }
+
+            for (const support of itemResult.supports ?? []) {
+              writeSupport(writer, support);
+            }
+          },
+        );
+      }
+    },
+  );
+
+  return writer.toString();
+}

package/src/serialize-usage-data.ts

@@ -0,0 +1,85 @@
+/**
+ * Usage Data & Item Statistics XML serialization (imsqti_usagedata_v3p0) — the
+ * EXPORT direction of the Usage Data specification, gated in tests by the round
+ * trip through our own parser, normalizer, and strict contracts schema.
+ */
+
+import type { QtiUsageDataDocument, QtiUsageStatistic, QtiUsageTargetObject } from "@conform-ed/contracts/qti/v3_0_1";
+
+import { XmlWriter, type AttributeValue } from "./xml-writer";
+
+const usageDataNamespace = "http://www.imsglobal.org/xsd/imsqti_usagedata_v3p0";
+const usageDataSchemaLocation = `${usageDataNamespace} https://purl.imsglobal.org/spec/qti/v3p0/schema/xsd/imsqti_usagedatav3p0_v1p0.xsd`;
+
+function writeTargetObjects(writer: XmlWriter, targetObjects: readonly QtiUsageTargetObject[]): void {
+  for (const target of targetObjects) {
+    writer.element("targetObject", [
+      ["identifier", target.identifier],
+      ["partIdentifier", target.partIdentifier],
+      ["objectType", target.objectType],
+    ]);
+  }
+}
+
+function statisticAttributes(statistic: QtiUsageStatistic): ReadonlyArray<readonly [string, AttributeValue]> {
+  return [
+    ["name", statistic.name],
+    ["glossary", statistic.glossary],
+    ["context", statistic.context],
+    ["caseCount", statistic.caseCount],
+    ["stdError", statistic.stdError],
+    ["stdDeviation", statistic.stdDeviation],
+    ["lastUpdated", statistic.lastUpdated],
+  ];
+}
+
+/** Serialize a usage data document against the official 3.0 binding. */
+export function serializeQtiUsageData(document: QtiUsageDataDocument): string {
+  const { usageData } = document;
+  const writer = new XmlWriter();
+
+  writer.line('<?xml version="1.0" encoding="UTF-8"?>');
+  writer.element(
+    "usageData",
+    [
+      ["xmlns", usageDataNamespace],
+      ["xmlns:xsi", "http://www.w3.org/2001/XMLSchema-instance"],
+      ["xsi:schemaLocation", usageDataSchemaLocation],
+      ["glossary", usageData.glossary],
+    ],
+    () => {
+      for (const statistic of usageData.statistics) {
+        if (statistic.kind === "ordinaryStatistic") {
+          writer.element("ordinaryStatistic", statisticAttributes(statistic), () => {
+            writeTargetObjects(writer, statistic.targetObjects);
+            writer.element("value", [], statistic.value.value);
+          });
+          continue;
+        }
+
+        writer.element("categorizedStatistic", statisticAttributes(statistic), () => {
+          writeTargetObjects(writer, statistic.targetObjects);
+          writer.element(
+            "mapping",
+            [
+              ["lowerBound", statistic.mapping.lowerBound],
+              ["upperBound", statistic.mapping.upperBound],
+              ["defaultValue", statistic.mapping.defaultValue],
+            ],
+            () => {
+              for (const entry of statistic.mapping.mapEntries) {
+                writer.element("mapEntry", [
+                  ["mapKey", entry.mapKey],
+                  ["mappedValue", entry.mappedValue],
+                  ["caseSensitive", entry.caseSensitive],
+                ]);
+              }
+            },
+          );
+        });
+      }
+    },
+  );
+
+  return writer.toString();
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+export type QtiFileKind = "html" | "other" | "xml" | "zip";
+export type QtiXmlStatus = "malformed" | "not-xml" | "well-formed";
+export type QtiSupportStatus =
+  | "known-broken-example"
+  | "not-xml"
+  | "supported"
+  | "unsupported-normalization"
+  | "unsupported-root"
+  | "zip-package";
+export type QtiValidationStatus = "invalid" | "parse-error" | "unsupported" | "valid";
+export type QtiVersion = "2.2" | "3.0.1";
+export type QtiSchemaSelectionKey =
+  | "qtiAccessForAllPnpDocument"
+  | "qtiAccessForAllPnpRecordsDocument"
+  | "qtiAssessmentItemDocument"
+  | "qtiAssessmentResultDocument"
+  | "qtiOutcomeDeclarationDocument"
+  | "qtiOutcomeProcessingDocument"
+  | "qtiResponseProcessingDocument"
+  | "qtiUsageDataDocument"
+  | "qtiAssessmentSectionDocument"
+  | "qtiAssessmentStimulusDocument"
+  | "qtiAssessmentTestDocument"
+  | "qtiManifestDocument"
+  | "qtiMetadataDocument";
+
+export interface QtiRootDetection {
+  rootName: string;
+  localName: string;
+  prefix?: string;
+  namespaceUri?: string;
+  inferredVersion?: QtiVersion;
+  schemaSelectionKey?: QtiSchemaSelectionKey;
+}
+
+export interface QtiExampleInventoryEntry {
+  absolutePath: string;
+  relativePath: string;
+  sourceGroup: string;
+  fileKind: QtiFileKind;
+  xmlStatus: QtiXmlStatus;
+  supportStatus: QtiSupportStatus;
+  rootName?: string;
+  localName?: string;
+  namespaceUri?: string;
+  inferredVersion?: QtiVersion;
+  schemaSelectionKey?: QtiSchemaSelectionKey;
+  contentHash: string;
+  note?: string;
+}
+
+export interface QtiExampleInventorySummary {
+  totalFiles: number;
+  byFileKind: Record<QtiFileKind, number>;
+  bySupportStatus: Record<QtiSupportStatus, number>;
+  byVersion: Record<string, number>;
+}
+
+export interface QtiExampleInventoryReport {
+  rootPath: string;
+  generatedAt: string;
+  entries: QtiExampleInventoryEntry[];
+  summary: QtiExampleInventorySummary;
+}
+
+export interface QtiValidationIssue {
+  path: string;
+  message: string;
+}
+
+export interface QtiValidationResult {
+  filePath: string;
+  rootDetection?: QtiRootDetection;
+  status: QtiValidationStatus;
+  schemaSelectionKey?: QtiSchemaSelectionKey;
+  normalizedDocument?: unknown;
+  issues: QtiValidationIssue[];
+}