@conform-ed/qti-xml 0.0.16

package/src/parse-xml.ts

@@ -0,0 +1,147 @@
+import { XMLParser } from "fast-xml-parser";
+import { SyntaxValidator } from "fast-xml-validator";
+
+export interface QtiXmlTextNode {
+  type: "text";
+  value: string;
+}
+
+export interface QtiXmlElementNode {
+  type: "element";
+  name: string;
+  localName: string;
+  prefix?: string;
+  namespaceUri?: string;
+  attributes: Record<string, string>;
+  children: QtiXmlNode[];
+}
+
+export type QtiXmlNode = QtiXmlElementNode | QtiXmlTextNode;
+
+const parser = new XMLParser({
+  preserveOrder: true,
+  ignoreAttributes: false,
+  attributeNamePrefix: "",
+  textNodeName: "#text",
+  commentPropName: "#comment",
+  trimValues: false,
+  parseTagValue: false,
+  parseAttributeValue: false,
+});
+
+function splitXmlName(name: string): { localName: string; prefix: string | undefined } {
+  const [prefix, localName] = name.includes(":") ? name.split(":", 2) : [undefined, name];
+  return {
+    prefix,
+    localName: localName ?? name,
+  };
+}
+
+function parseValidationError(error: unknown): string {
+  if (!error || typeof error !== "object") {
+    return "Invalid XML.";
+  }
+
+  const candidate = error as { err?: { msg?: string } };
+  return candidate.err?.msg ?? JSON.stringify(error);
+}
+
+function buildNamespaceScope(
+  parentScope: Record<string, string>,
+  attributes: Record<string, string>,
+): Record<string, string> {
+  const nextScope = { ...parentScope };
+
+  for (const [name, value] of Object.entries(attributes)) {
+    if (name === "xmlns") {
+      nextScope[""] = value;
+      continue;
+    }
+
+    if (name.startsWith("xmlns:")) {
+      nextScope[name.slice("xmlns:".length)] = value;
+    }
+  }
+
+  return nextScope;
+}
+
+function stripNamespaceAttributes(attributes: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(attributes).filter(([name]) => name !== "xmlns" && !name.startsWith("xmlns:")),
+  );
+}
+
+function buildXmlNodes(entries: unknown, parentScope: Record<string, string>): QtiXmlNode[] {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+
+  const nodes: QtiXmlNode[] = [];
+
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+
+    const record = entry as Record<string, unknown>;
+
+    const textValue = record["#text"];
+    if (
+      (typeof textValue === "string" || typeof textValue === "number" || typeof textValue === "boolean") &&
+      !Array.isArray(textValue)
+    ) {
+      nodes.push({
+        type: "text",
+        value: String(textValue),
+      });
+      continue;
+    }
+
+    const elementName = Object.keys(record).find((key) => key !== ":@" && key !== "#comment" && !key.startsWith("?"));
+
+    if (!elementName) {
+      continue;
+    }
+
+    const rawAttributes = record[":@"];
+    const attributes =
+      rawAttributes && typeof rawAttributes === "object"
+        ? Object.fromEntries(
+            Object.entries(rawAttributes as Record<string, unknown>).map(([name, value]) => [name, String(value)]),
+          )
+        : {};
+    const namespaceScope = buildNamespaceScope(parentScope, attributes);
+    const strippedAttributes = stripNamespaceAttributes(attributes);
+    const { localName, prefix } = splitXmlName(elementName);
+    const namespaceUri = prefix ? namespaceScope[prefix] : namespaceScope[""];
+
+    nodes.push({
+      type: "element",
+      name: elementName,
+      localName,
+      ...(prefix !== undefined ? { prefix } : {}),
+      ...(namespaceUri !== undefined ? { namespaceUri } : {}),
+      attributes: strippedAttributes,
+      children: buildXmlNodes(record[elementName], namespaceScope),
+    });
+  }
+
+  return nodes;
+}
+
+export function parseXmlDocument(xml: string): QtiXmlElementNode {
+  const validationResult = SyntaxValidator.validate(xml);
+  if (validationResult !== true) {
+    throw new Error(parseValidationError(validationResult));
+  }
+
+  const nodes = buildXmlNodes(parser.parse(xml), {});
+  const root = nodes.find((node) => node.type === "element");
+
+  if (!root || root.type !== "element") {
+    throw new Error("XML document does not contain a root element.");
+  }
+
+  return root;
+}

package/src/root-detection.ts

@@ -0,0 +1,214 @@
+import type { QtiRootDetection, QtiSchemaSelectionKey, QtiVersion } from "./types";
+
+const qtiV22Namespace = "http://www.imsglobal.org/xsd/imsqti_v2p2";
+const qtiV22MetadataNamespace = "http://www.imsglobal.org/xsd/imsqti_metadata_v2p2";
+const qtiV22ResultsNamespace = "http://www.imsglobal.org/xsd/imsqti_result_v2p2";
+const qtiV22UsageDataNamespace = "http://www.imsglobal.org/xsd/imsqti_usagedata_v2p2";
+const qtiV22ManifestNamespace = "http://www.imsglobal.org/xsd/imscp_v1p1";
+const qtiV30AsiNamespace = "http://www.imsglobal.org/xsd/imsqtiasi_v3p0";
+const qtiV30ResultsNamespace = "http://www.imsglobal.org/xsd/imsqti_result_v3p0";
+const qtiV30MetadataNamespace = "http://www.imsglobal.org/xsd/imsqti_metadata_v3p0";
+const qtiV30ManifestNamespace = "http://www.imsglobal.org/xsd/qti/qtiv3p0/imscp_v1p1";
+const qtiV30AfaPnpNamespace = "http://www.imsglobal.org/xsd/qti/qtiv3p0/imsafa3p0pnp_v1p0";
+const qtiV30UsageDataNamespace = "http://www.imsglobal.org/xsd/imsqti_usagedata_v3p0";
+
+const attributePattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+
+function stripLeadingXmlProlog(value: string): string {
+  let remaining = value.replace(/^\uFEFF/u, "");
+
+  while (true) {
+    const next = remaining
+      .replace(/^\s+/u, "")
+      .replace(/^<\?xml[\s\S]*?\?>/u, "")
+      .replace(/^\s+/u, "")
+      .replace(/^<!--[\s\S]*?-->/u, "")
+      .replace(/^\s+/u, "")
+      .replace(/^<!DOCTYPE[\s\S]*?>/iu, "");
+
+    if (next === remaining) {
+      return remaining.replace(/^\s+/u, "");
+    }
+
+    remaining = next;
+  }
+}
+
+function parseAttributes(rawAttributes: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+
+  for (const match of rawAttributes.matchAll(attributePattern)) {
+    const name = match[1];
+    if (!name) {
+      continue;
+    }
+    const doubleQuoted = match[3];
+    const singleQuoted = match[4];
+    attributes[name] = doubleQuoted ?? singleQuoted ?? "";
+  }
+
+  return attributes;
+}
+
+function splitXmlName(name: string): { localName: string; prefix: string | undefined } {
+  const [prefix, localName] = name.includes(":") ? name.split(":", 2) : [undefined, name];
+  return {
+    prefix,
+    localName: localName ?? name,
+  };
+}
+
+function inferVersion(namespaceUri: string | undefined, localName: string, xml: string): QtiVersion | undefined {
+  if (
+    namespaceUri === qtiV22Namespace ||
+    namespaceUri === qtiV22MetadataNamespace ||
+    namespaceUri === qtiV22ResultsNamespace ||
+    namespaceUri === qtiV22UsageDataNamespace
+  ) {
+    return "2.2";
+  }
+
+  if (namespaceUri === qtiV22ManifestNamespace) {
+    if (xml.includes("qtiv2p2") || xml.includes("QTIv2.2 Package")) {
+      return "2.2";
+    }
+  }
+
+  if (
+    namespaceUri === qtiV30AsiNamespace ||
+    namespaceUri === qtiV30ResultsNamespace ||
+    namespaceUri === qtiV30MetadataNamespace ||
+    namespaceUri === qtiV30AfaPnpNamespace ||
+    namespaceUri === qtiV30UsageDataNamespace
+  ) {
+    return "3.0.1";
+  }
+
+  if (namespaceUri === qtiV30ManifestNamespace) {
+    return "3.0.1";
+  }
+
+  if (localName === "manifest" && xml.includes("qtiv2p2")) {
+    return "2.2";
+  }
+
+  return undefined;
+}
+
+function inferSchemaSelectionKey(
+  version: QtiVersion | undefined,
+  namespaceUri: string | undefined,
+  localName: string,
+): QtiSchemaSelectionKey | undefined {
+  if (!version) {
+    return undefined;
+  }
+
+  if (version === "2.2") {
+    if (namespaceUri === qtiV22Namespace) {
+      switch (localName) {
+        case "assessmentItem":
+          return "qtiAssessmentItemDocument";
+        case "assessmentSection":
+          return "qtiAssessmentSectionDocument";
+        case "assessmentStimulus":
+          return "qtiAssessmentStimulusDocument";
+        case "assessmentTest":
+          return "qtiAssessmentTestDocument";
+      }
+    }
+
+    if (namespaceUri === qtiV22MetadataNamespace && localName === "qtiMetadata") {
+      return "qtiMetadataDocument";
+    }
+
+    if (namespaceUri === qtiV22ResultsNamespace && localName === "assessmentResult") {
+      return "qtiAssessmentResultDocument";
+    }
+
+    if (namespaceUri === qtiV22ManifestNamespace && localName === "manifest") {
+      return "qtiManifestDocument";
+    }
+
+    if (namespaceUri === qtiV22UsageDataNamespace && localName === "usageData") {
+      return "qtiUsageDataDocument";
+    }
+  }
+
+  if (version === "3.0.1") {
+    if (namespaceUri === qtiV30AsiNamespace) {
+      switch (localName) {
+        case "qti-assessment-item":
+          return "qtiAssessmentItemDocument";
+        case "qti-assessment-section":
+          return "qtiAssessmentSectionDocument";
+        case "qti-assessment-stimulus":
+          return "qtiAssessmentStimulusDocument";
+        case "qti-assessment-test":
+          return "qtiAssessmentTestDocument";
+        case "qti-outcome-declaration":
+          return "qtiOutcomeDeclarationDocument";
+        case "qti-outcome-processing":
+          return "qtiOutcomeProcessingDocument";
+        case "qti-response-processing":
+          return "qtiResponseProcessingDocument";
+      }
+    }
+
+    if (namespaceUri === qtiV30MetadataNamespace && localName === "qtiMetadata") {
+      return "qtiMetadataDocument";
+    }
+
+    if (namespaceUri === qtiV30ResultsNamespace && localName === "assessmentResult") {
+      return "qtiAssessmentResultDocument";
+    }
+
+    if (namespaceUri === qtiV30UsageDataNamespace && localName === "usageData") {
+      return "qtiUsageDataDocument";
+    }
+
+    if (namespaceUri === qtiV30ManifestNamespace && localName === "manifest") {
+      return "qtiManifestDocument";
+    }
+
+    if (namespaceUri === qtiV30AfaPnpNamespace) {
+      switch (localName) {
+        case "access-for-all-pnp":
+          return "qtiAccessForAllPnpDocument";
+        case "access-for-all-pnp-records":
+          return "qtiAccessForAllPnpRecordsDocument";
+      }
+    }
+  }
+
+  return undefined;
+}
+
+export function detectQtiRoot(xml: string): QtiRootDetection | undefined {
+  const stripped = stripLeadingXmlProlog(xml);
+  const match = stripped.match(/^<([A-Za-z_][A-Za-z0-9:._-]*)([\s\S]*?)(?:\/?)>/u);
+
+  if (!match) {
+    return undefined;
+  }
+
+  const rootName = match[1];
+  if (!rootName) {
+    return undefined;
+  }
+  const rawAttributes = match[2] ?? "";
+  const attributes = parseAttributes(rawAttributes);
+  const { localName, prefix } = splitXmlName(rootName);
+  const namespaceUri = prefix ? attributes[`xmlns:${prefix}`] : attributes["xmlns"];
+  const inferredVersion = inferVersion(namespaceUri, localName, xml);
+  const schemaSelectionKey = inferSchemaSelectionKey(inferredVersion, namespaceUri, localName);
+
+  return {
+    rootName,
+    localName,
+    ...(prefix !== undefined ? { prefix } : {}),
+    ...(namespaceUri !== undefined ? { namespaceUri } : {}),
+    ...(inferredVersion !== undefined ? { inferredVersion } : {}),
+    ...(schemaSelectionKey !== undefined ? { schemaSelectionKey } : {}),
+  };
+}

package/src/schema-selection.ts

@@ -0,0 +1,78 @@
+import * as QtiV2_2 from "@conform-ed/contracts/qti/v2_2";
+import * as QtiV3_0_1 from "@conform-ed/contracts/qti/v3_0_1";
+
+import type { QtiRootDetection, QtiSchemaSelectionKey, QtiVersion } from "./types";
+
+type SafeParseSchema = {
+  safeParse(input: unknown): unknown;
+};
+
+export interface QtiSchemaSelection {
+  version: QtiVersion;
+  key: QtiSchemaSelectionKey;
+  schema: SafeParseSchema;
+}
+
+const registry: Record<string, SafeParseSchema> = {
+  "2.2:qtiAssessmentItemDocument": QtiV2_2.QtiAssessmentItemDocumentSchema as SafeParseSchema,
+  "2.2:qtiAssessmentResultDocument": QtiV2_2.QtiAssessmentResultDocumentSchema as SafeParseSchema,
+  "2.2:qtiAssessmentSectionDocument": QtiV2_2.QtiAssessmentSectionDocumentSchema as SafeParseSchema,
+  "2.2:qtiAssessmentStimulusDocument": QtiV2_2.QtiAssessmentStimulusDocumentSchema as SafeParseSchema,
+  "2.2:qtiAssessmentTestDocument": QtiV2_2.QtiAssessmentTestDocumentSchema as SafeParseSchema,
+  "2.2:qtiManifestDocument": QtiV2_2.QtiManifestDocumentSchema as SafeParseSchema,
+  "2.2:qtiMetadataDocument": QtiV2_2.QtiMetadataDocumentSchema as SafeParseSchema,
+  "2.2:qtiUsageDataDocument": QtiV2_2.QtiUsageDataDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAccessForAllPnpDocument": QtiV3_0_1.QtiAccessForAllPnpDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAccessForAllPnpRecordsDocument": QtiV3_0_1.QtiAccessForAllPnpRecordsDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAssessmentItemDocument": QtiV3_0_1.QtiAssessmentItemDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAssessmentResultDocument": QtiV3_0_1.QtiAssessmentResultDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAssessmentSectionDocument": QtiV3_0_1.QtiAssessmentSectionDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAssessmentStimulusDocument": QtiV3_0_1.QtiAssessmentStimulusDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiAssessmentTestDocument": QtiV3_0_1.QtiAssessmentTestDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiManifestDocument": QtiV3_0_1.QtiManifestDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiMetadataDocument": QtiV3_0_1.QtiMetadataDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiOutcomeDeclarationDocument": QtiV3_0_1.QtiOutcomeDeclarationDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiOutcomeProcessingDocument": QtiV3_0_1.QtiOutcomeProcessingDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiResponseProcessingDocument": QtiV3_0_1.QtiResponseProcessingDocumentSchema as SafeParseSchema,
+  "3.0.1:qtiUsageDataDocument": QtiV3_0_1.QtiUsageDataDocumentSchema as SafeParseSchema,
+};
+
+const normalizationImplemented = new Set<string>([
+  "2.2:qtiAssessmentItemDocument",
+  "2.2:qtiUsageDataDocument",
+  "3.0.1:qtiAccessForAllPnpDocument",
+  "3.0.1:qtiAccessForAllPnpRecordsDocument",
+  "2.2:qtiManifestDocument",
+  "3.0.1:qtiAssessmentItemDocument",
+  "3.0.1:qtiAssessmentResultDocument",
+  "3.0.1:qtiAssessmentSectionDocument",
+  "3.0.1:qtiAssessmentStimulusDocument",
+  "3.0.1:qtiAssessmentTestDocument",
+  "3.0.1:qtiManifestDocument",
+  "3.0.1:qtiMetadataDocument",
+  "3.0.1:qtiOutcomeDeclarationDocument",
+  "3.0.1:qtiOutcomeProcessingDocument",
+  "3.0.1:qtiResponseProcessingDocument",
+  "3.0.1:qtiUsageDataDocument",
+]);
+
+export function isNormalizationImplemented(version: QtiVersion, key: QtiSchemaSelectionKey): boolean {
+  return normalizationImplemented.has(`${version}:${key}`);
+}
+
+export function selectQtiSchema(rootDetection: QtiRootDetection): QtiSchemaSelection | undefined {
+  if (!rootDetection.inferredVersion || !rootDetection.schemaSelectionKey) {
+    return undefined;
+  }
+
+  const schema = registry[`${rootDetection.inferredVersion}:${rootDetection.schemaSelectionKey}`];
+  if (!schema) {
+    return undefined;
+  }
+
+  return {
+    version: rootDetection.inferredVersion,
+    key: rootDetection.schemaSelectionKey,
+    schema,
+  };
+}