@longsightgroup/qti3-migrator 0.9.5

package/src/source.ts

@@ -0,0 +1,251 @@
+import { unzipSync } from "fflate";
+import { decodeUtf8 } from "@longsightgroup/qti3-core";
+import { diagnostic } from "./diagnostics.js";
+import type {
+  QtiMigrationDetectionResult,
+  QtiMigrationDiagnostic,
+  QtiMigrationSourceInput,
+} from "./types.js";
+import { attr, findAllDescendantsByLocalName, localName, parseXml, textOf } from "./xml.js";
+
+export interface MigrationEntry {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+  readonly text?: string | undefined;
+}
+
+export interface MigrationSource {
+  readonly filename?: string | undefined;
+  readonly isPackage: boolean;
+  readonly entries: readonly MigrationEntry[];
+  readonly xml?: string | undefined;
+}
+
+export function readMigrationSource(input: QtiMigrationSourceInput): MigrationSource {
+  if (input.xml !== undefined) {
+    return { filename: input.filename, isPackage: false, entries: [], xml: input.xml };
+  }
+  if (!input.bytes) {
+    throw new Error("QTI migration input must include xml or bytes.");
+  }
+  if (isZip(input.bytes)) {
+    const unzipped = unzipSync(input.bytes);
+    const entries = Object.entries(unzipped)
+      .filter(([path]) => !path.endsWith("/"))
+      .map(([path, bytes]) => ({
+        path: path.replaceAll("\\", "/"),
+        bytes,
+        text: isTextPath(path) ? decodeUtf8(bytes) : undefined,
+      }));
+    return { filename: input.filename, isPackage: true, entries };
+  }
+  return {
+    filename: input.filename,
+    isPackage: false,
+    entries: [],
+    xml: decodeUtf8(input.bytes),
+  };
+}
+
+export function detectQtiMigrationSource(
+  input: QtiMigrationSourceInput,
+): QtiMigrationDetectionResult {
+  try {
+    const source = readMigrationSource(input);
+    return detectMigrationSource(source);
+  } catch (error) {
+    return {
+      supported: false,
+      confidence: 0,
+      reason: error instanceof Error ? error.message : "source-read-failed",
+      isPackage: false,
+    };
+  }
+}
+
+export function detectMigrationSource(source: MigrationSource): QtiMigrationDetectionResult {
+  if (source.isPackage) {
+    const manifest = source.entries.find((entry) => entry.path.toLowerCase() === "imsmanifest.xml");
+    if (!manifest?.text) {
+      return {
+        supported: false,
+        confidence: 0.2,
+        reason: "package-manifest-missing",
+        isPackage: true,
+      };
+    }
+    return detectManifest(manifest.text);
+  }
+  if (!source.xml) {
+    return { supported: false, confidence: 0, reason: "xml-missing", isPackage: false };
+  }
+  return detectItemXml(source.xml);
+}
+
+export interface LegacyManifest {
+  readonly title: string;
+  readonly resources: readonly LegacyManifestResource[];
+  readonly itemHrefs: readonly string[];
+  readonly testHrefs: readonly string[];
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+}
+
+export interface LegacyManifestResource {
+  readonly identifier: string;
+  readonly type: string;
+  readonly href?: string | undefined;
+  readonly files: readonly string[];
+}
+
+export function parseLegacyManifest(xml: string): LegacyManifest {
+  const diagnostics: QtiMigrationDiagnostic[] = [];
+  const doc = parseXml(xml, "imsmanifest.xml");
+  const root = doc.documentElement;
+  const title =
+    textOf(findAllDescendantsByLocalName(root, "title")[0]) ||
+    attr(root, "identifier") ||
+    "Imported QTI Package";
+  const resourceNodes = findAllDescendantsByLocalName(root, "resource");
+  const resources = resourceNodes.map((resource, index) => {
+    const files = findAllDescendantsByLocalName(resource, "file")
+      .map((file) => attr(file, "href"))
+      .filter((href): href is string => Boolean(href));
+    return {
+      identifier: attr(resource, "identifier") ?? `RESOURCE_${index + 1}`,
+      type: attr(resource, "type") ?? "",
+      href: attr(resource, "href") ?? files.find((file) => file.toLowerCase().endsWith(".xml")),
+      files,
+    };
+  });
+  const itemHrefs = resources
+    .filter((resource) => isLegacyItemResource(resource.type))
+    .map((resource) => resource.href)
+    .filter((href): href is string => Boolean(href));
+  const testHrefs = resources
+    .filter((resource) => isLegacyTestResource(resource.type))
+    .map((resource) => resource.href)
+    .filter((href): href is string => Boolean(href));
+  if (!itemHrefs.length && !testHrefs.length) {
+    diagnostics.push(
+      diagnostic(
+        "manifest_items_missing",
+        "error",
+        "Manifest does not contain supported QTI 1.2 or QTI 2.x item/test resources.",
+        { path: "imsmanifest.xml" },
+      ),
+    );
+  }
+  return { title, resources, itemHrefs, testHrefs, diagnostics };
+}
+
+function detectManifest(xml: string): QtiMigrationDetectionResult {
+  const manifest = parseLegacyManifest(xml);
+  const typeText = manifest.resources.map((resource) => resource.type.toLowerCase()).join(" ");
+  if (typeText.includes("v2p2")) {
+    return {
+      supported: true,
+      sourceFormat: "qti22",
+      confidence: 0.9,
+      reason: "manifest-qti22",
+      isPackage: true,
+    };
+  }
+  if (typeText.includes("v2p1") || typeText.includes("imsqti_item_xmlv2")) {
+    return {
+      supported: true,
+      sourceFormat: "qti21",
+      confidence: 0.85,
+      reason: "manifest-qti2x",
+      isPackage: true,
+    };
+  }
+  if (typeText.includes("qti_xmlv1p2") || typeText.includes("imsqti_xmlv1p2")) {
+    return {
+      supported: true,
+      sourceFormat: "qti12",
+      confidence: 0.85,
+      reason: "manifest-qti12",
+      isPackage: true,
+    };
+  }
+  return {
+    supported: manifest.itemHrefs.length > 0,
+    sourceFormat: manifest.itemHrefs.length > 0 ? "qti21" : undefined,
+    confidence: manifest.itemHrefs.length > 0 ? 0.45 : 0.1,
+    reason:
+      manifest.itemHrefs.length > 0 ? "manifest-legacy-item-resource" : "manifest-unsupported",
+    isPackage: true,
+  };
+}
+
+function detectItemXml(xml: string): QtiMigrationDetectionResult {
+  const doc = parseXml(xml, "item");
+  const root = doc.documentElement;
+  const rootName = localName(root);
+  const serializedRoot = root.nodeName.toLowerCase();
+  const namespaceText = [
+    attr(root, "xmlns"),
+    attr(root, "xmlns:qti"),
+    attr(root, "xsi:schemaLocation"),
+    attr(root, "schemaLocation"),
+    serializedRoot,
+  ]
+    .join(" ")
+    .toLowerCase();
+  if (rootName === "assessmentitem") {
+    if (namespaceText.includes("v2p2")) {
+      return {
+        supported: true,
+        sourceFormat: "qti22",
+        confidence: 0.9,
+        reason: "assessmentitem-qti22",
+        isPackage: false,
+      };
+    }
+    return {
+      supported: true,
+      sourceFormat: "qti21",
+      confidence: 0.85,
+      reason: "assessmentitem-qti2x",
+      isPackage: false,
+    };
+  }
+  if (rootName === "questestinterop" || rootName === "item") {
+    return {
+      supported: true,
+      sourceFormat: "qti12",
+      confidence: 0.75,
+      reason: "qti12-root",
+      isPackage: false,
+    };
+  }
+  return {
+    supported: false,
+    confidence: 0,
+    reason: `unsupported-root-${rootName}`,
+    isPackage: false,
+  };
+}
+
+function isLegacyItemResource(type: string): boolean {
+  const value = type.toLowerCase();
+  return (
+    value.includes("imsqti_item_xmlv2") ||
+    value.includes("imsqti_item_xmlv1p2") ||
+    value.includes("imsqti_xmlv1p2") ||
+    value.includes("qti_xmlv1p2")
+  );
+}
+
+function isLegacyTestResource(type: string): boolean {
+  const value = type.toLowerCase();
+  return value.includes("imsqti_test_xmlv2");
+}
+
+function isZip(bytes: Uint8Array): boolean {
+  return bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b;
+}
+
+function isTextPath(path: string): boolean {
+  return /\.(xml|html?|txt|json|css|js)$/i.test(path);
+}

package/src/text.ts

@@ -0,0 +1,21 @@
+export function normalizeIdentifier(value: string | null | undefined, fallback = "ID"): string {
+  const source = (value ?? "").trim() || fallback;
+  const normalized = source.replace(/[^A-Za-z0-9_]/g, "_").replace(/^[^A-Za-z_]+/, "");
+  return normalized || fallback;
+}
+
+export function stripTags(html: string): string {
+  return html.replace(/<[^>]*>/g, "").trim();
+}
+
+export function trustedFragment(html: string): string {
+  return html.trim();
+}
+
+export function escapeText(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/src/types.ts

@@ -0,0 +1,73 @@
+import type { Qti3AuthoringItem, Qti3WriterDiagnostic } from "@longsightgroup/qti3-writer";
+
+export type QtiMigrationSourceFormat = "qti12" | "qti21" | "qti22";
+
+export type QtiMigrationRepairPolicy = "none" | "safe";
+
+export type QtiMigrationUnsupportedPolicy = "diagnostic" | "stub" | "skip";
+
+export interface QtiMigrationSourceInput {
+  readonly filename?: string | undefined;
+  readonly bytes?: Uint8Array | undefined;
+  readonly xml?: string | undefined;
+  readonly mime?: string | undefined;
+}
+
+export interface QtiMigrationOptions {
+  readonly repairPolicy?: QtiMigrationRepairPolicy | undefined;
+  readonly unsupportedPolicy?: QtiMigrationUnsupportedPolicy | undefined;
+}
+
+export interface ResolvedQtiMigrationOptions {
+  readonly repairPolicy: QtiMigrationRepairPolicy;
+  readonly unsupportedPolicy: QtiMigrationUnsupportedPolicy;
+}
+
+export interface QtiMigrationDetectionResult {
+  readonly supported: boolean;
+  readonly sourceFormat?: QtiMigrationSourceFormat | undefined;
+  readonly confidence: number;
+  readonly reason: string;
+  readonly isPackage: boolean;
+}
+
+export type QtiMigrationDiagnosticSeverity = "info" | "warning" | "error";
+
+export interface QtiMigrationDiagnostic {
+  readonly code: string;
+  readonly severity: QtiMigrationDiagnosticSeverity;
+  readonly message: string;
+  readonly path?: string | undefined;
+  readonly sourceFormat?: QtiMigrationSourceFormat | undefined;
+  readonly writerDiagnostics?: readonly Qti3WriterDiagnostic[] | undefined;
+}
+
+export interface QtiMigrationPart {
+  readonly identifier: string;
+  readonly title: string;
+  readonly itemHrefs: readonly string[];
+}
+
+export interface QtiMigrationAsset {
+  readonly path: string;
+  readonly data?: Uint8Array | undefined;
+  readonly mediaType?: string | undefined;
+}
+
+export interface QtiMigrationItemResult {
+  readonly identifier: string;
+  readonly title: string;
+  readonly href: string;
+  readonly authoringItem?: Qti3AuthoringItem | undefined;
+  readonly xml?: string | undefined;
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+}
+
+export interface QtiMigrationResult {
+  readonly title: string;
+  readonly sourceFormat?: QtiMigrationSourceFormat | undefined;
+  readonly parts: readonly QtiMigrationPart[];
+  readonly items: readonly QtiMigrationItemResult[];
+  readonly assets: readonly QtiMigrationAsset[];
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+}

package/src/xml.ts

@@ -0,0 +1,119 @@
+import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
+
+export type XmlDocument = Document;
+export type XmlElement = Element;
+export type XmlNode = Node;
+
+const parser = new DOMParser();
+const serializer = new XMLSerializer();
+
+export function parseXml(xml: string, context: string): XmlDocument {
+  const doc = parser.parseFromString(normalizeXml(xml), "text/xml");
+  if (doc.documentElement.nodeName === "parsererror") {
+    throw new Error(`Failed to parse XML (${context}).`);
+  }
+  return doc;
+}
+
+export function serializeNode(node: XmlNode): string {
+  return serializer.serializeToString(node);
+}
+
+export function serializeChildren(element: XmlElement): string {
+  let out = "";
+  for (let index = 0; index < element.childNodes.length; index += 1) {
+    const child = element.childNodes.item(index);
+    out += serializeNode(child);
+  }
+  return out;
+}
+
+export function attr(element: XmlElement | null | undefined, key: string): string | null {
+  if (!element) return null;
+  const alternate = key.includes("-")
+    ? key.replace(/-([a-z])/g, (_match, char: string) => char.toUpperCase())
+    : key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+  const target = key.toLowerCase();
+  for (let index = 0; index < element.attributes.length; index += 1) {
+    const attribute = element.attributes.item(index);
+    if (!attribute) continue;
+    if (
+      attribute.name === key ||
+      attribute.name === alternate ||
+      attribute.name.toLowerCase() === target
+    ) {
+      return attribute.value;
+    }
+  }
+  return null;
+}
+
+export function localName(element: XmlElement | null | undefined): string {
+  const raw = element?.localName ?? element?.nodeName ?? "";
+  return (raw.includes(":") ? (raw.split(":").pop() ?? raw) : raw).toLowerCase();
+}
+
+export function childElements(node: XmlElement): XmlElement[] {
+  const out: XmlElement[] = [];
+  for (let index = 0; index < node.childNodes.length; index += 1) {
+    const child = node.childNodes.item(index);
+    if (isXmlElement(child)) out.push(child);
+  }
+  return out;
+}
+
+export function findDescendantByLocalName(
+  root: XmlElement | null | undefined,
+  tag: string,
+): XmlElement | null {
+  if (!root) return null;
+  const target = tag.toLowerCase();
+  for (const child of childElements(root)) {
+    if (localName(child) === target) return child;
+    const nested = findDescendantByLocalName(child, target);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+export function findAllDescendantsByLocalName(
+  root: XmlElement | null | undefined,
+  tag: string,
+): XmlElement[] {
+  return findAllDescendantsByAnyLocalName(root, [tag]);
+}
+
+export function findAllDescendantsByAnyLocalName(
+  root: XmlElement | null | undefined,
+  tags: readonly string[],
+): XmlElement[] {
+  if (!root) return [];
+  const tagSet = new Set(tags.map((tag) => tag.toLowerCase()));
+  const matches: XmlElement[] = [];
+  const walk = (node: XmlElement): void => {
+    for (const child of childElements(node)) {
+      if (tagSet.has(localName(child))) matches.push(child);
+      if (child.childNodes.length) walk(child);
+    }
+  };
+  walk(root);
+  return matches;
+}
+
+export function toNumber(value: string | null | undefined): number | undefined {
+  if (value == null || value.trim() === "") return undefined;
+  const num = Number(value);
+  return Number.isFinite(num) ? num : undefined;
+}
+
+export function textOf(element: XmlElement | null | undefined): string {
+  return (element?.textContent ?? "").trim();
+}
+
+export function isXmlElement(node: XmlNode | null): node is XmlElement {
+  return node?.nodeType === 1;
+}
+
+function normalizeXml(xml: string): string {
+  return xml.replace(/^\uFEFF/, "").trimStart();
+}