@conform-ed/qti-xml 0.0.16

package/src/validate-package.ts

@@ -0,0 +1,408 @@
+import { createReadStream } from "node:fs";
+import { access, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { Unzip, UnzipInflate, unzipSync } from "fflate";
+
+import type { QtiValidationIssue, QtiValidationResult } from "./types";
+import { validateQtiXmlContent } from "./validate";
+
+export interface QtiPackageValidationResult {
+  packagePath: string;
+  manifestPath?: string;
+  status: "invalid" | "unsupported" | "valid";
+  issues: QtiValidationIssue[];
+  manifestValidation?: QtiValidationResult;
+  referencedDocumentResults: QtiValidationResult[];
+}
+
+/** How the manifest and its referenced documents are read — from disk, or from a ZIP. */
+interface PackageSource {
+  /** The path reported as `packagePath` in the result. */
+  readonly reportPath: string;
+  /** The imsmanifest.xml content + the sourcePath xi:includes resolve against, or null. */
+  readManifest(): Promise<{ xml: string; sourcePath: string } | null>;
+  /** A referenced document's content, or null when the package omits it. */
+  readReferenced(href: string): Promise<{ xml: string; sourcePath: string } | null>;
+}
+
+function prependIssues(prefix: string, issues: QtiValidationIssue[]): QtiValidationIssue[] {
+  return issues.map((issue) => ({
+    path: `${prefix}${issue.path === "$" ? "" : issue.path.slice(1)}`,
+    message: issue.message,
+  }));
+}
+
+function hasManifestShape(value: unknown): value is {
+  manifest: {
+    resources?: Array<{
+      href?: string;
+      files?: Array<{ href: string }>;
+    }>;
+  };
+} {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    "manifest" in value &&
+    (value as { manifest?: unknown }).manifest &&
+    typeof (value as { manifest?: unknown }).manifest === "object",
+  );
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The shared manifest + referenced-document validation, independent of the source. */
+async function validatePackage(source: PackageSource): Promise<QtiPackageValidationResult> {
+  const manifest = await source.readManifest();
+  if (!manifest) {
+    return {
+      packagePath: source.reportPath,
+      status: "unsupported",
+      issues: [{ path: "$", message: "Package does not contain imsmanifest.xml at its root." }],
+      referencedDocumentResults: [],
+    };
+  }
+
+  const manifestValidation = await validateQtiXmlContent(manifest.xml, { sourcePath: manifest.sourcePath });
+  const issues = prependIssues("$.manifest", manifestValidation.issues);
+
+  if (manifestValidation.status !== "valid") {
+    return {
+      packagePath: source.reportPath,
+      manifestPath: manifest.sourcePath,
+      status: manifestValidation.status === "unsupported" ? "unsupported" : "invalid",
+      issues,
+      manifestValidation,
+      referencedDocumentResults: [],
+    };
+  }
+
+  if (!hasManifestShape(manifestValidation.normalizedDocument)) {
+    return {
+      packagePath: source.reportPath,
+      manifestPath: manifest.sourcePath,
+      status: "unsupported",
+      issues: [{ path: "$.manifest", message: "Manifest normalized shape is not available for package validation." }],
+      manifestValidation,
+      referencedDocumentResults: [],
+    };
+  }
+
+  const referencedXmlFiles = new Set<string>();
+
+  for (const resource of manifestValidation.normalizedDocument.manifest.resources ?? []) {
+    if (resource.href?.toLowerCase().endsWith(".xml")) {
+      referencedXmlFiles.add(resource.href);
+    }
+
+    for (const file of resource.files ?? []) {
+      if (file.href.toLowerCase().endsWith(".xml")) {
+        referencedXmlFiles.add(file.href);
+      }
+    }
+  }
+
+  const referencedDocumentResults: QtiValidationResult[] = [];
+
+  for (const relativeHref of [...referencedXmlFiles].sort()) {
+    const referenced = await source.readReferenced(relativeHref);
+
+    if (!referenced) {
+      issues.push({
+        path: "$.manifest.resources",
+        message: `Referenced file is missing from the package: ${relativeHref}`,
+      });
+      continue;
+    }
+
+    const result = await validateQtiXmlContent(referenced.xml, { sourcePath: referenced.sourcePath });
+    referencedDocumentResults.push(result);
+
+    if (result.status !== "valid") {
+      issues.push(
+        ...prependIssues(
+          `$.resources[${relativeHref}]`,
+          result.issues.length
+            ? result.issues
+            : [{ path: "$", message: `Referenced XML validation status: ${result.status}` }],
+        ),
+      );
+    }
+  }
+
+  return {
+    packagePath: source.reportPath,
+    manifestPath: manifest.sourcePath,
+    status: issues.length === 0 ? "valid" : "invalid",
+    issues,
+    manifestValidation,
+    referencedDocumentResults,
+  };
+}
+
+function directorySource(directoryPath: string): PackageSource {
+  const manifestPath = path.join(directoryPath, "imsmanifest.xml");
+  return {
+    reportPath: directoryPath,
+    async readManifest() {
+      if (!(await fileExists(manifestPath))) {
+        return null;
+      }
+      return { xml: await readFile(manifestPath, "utf8"), sourcePath: manifestPath };
+    },
+    async readReferenced(href) {
+      const absoluteHref = path.resolve(directoryPath, href);
+      if (!(await fileExists(absoluteHref))) {
+        return null;
+      }
+      return { xml: await readFile(absoluteHref, "utf8"), sourcePath: absoluteHref };
+    },
+  };
+}
+
+/** The first two bytes of every ZIP local-file/empty/spanned record ("PK"). */
+function isZipArchive(bytes: Uint8Array): boolean {
+  return bytes[0] === 0x50 && bytes[1] === 0x4b;
+}
+
+/** Normalize a manifest href to the forward-slash, no-"./" form ZIP entries use. */
+function zipEntryKey(href: string): string {
+  return href.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+
+/** Validation only ever needs the XML; media (the bulk of a package) is never inflated. */
+function isXmlEntry(name: string): boolean {
+  return name.toLowerCase().endsWith(".xml");
+}
+
+function concatChunks(chunks: readonly Uint8Array[]): Uint8Array {
+  if (chunks.length === 1) {
+    return chunks[0]!;
+  }
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+/**
+ * Stream a ZIP from disk and write only its `.xml` entries to `destDir`, preserving
+ * relative structure. Memory stays bounded to roughly one entry plus stream buffers
+ * regardless of total package size — media entries are skipped without inflation.
+ * Guards against zip-slip (entry names escaping destDir).
+ */
+async function extractXmlEntriesToDir(zipPath: string, destDir: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const unzip = new Unzip();
+    unzip.register(UnzipInflate);
+
+    const writes: Array<Promise<void>> = [];
+    let failed = false;
+    const fail = (error: unknown): void => {
+      if (!failed) {
+        failed = true;
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    };
+
+    unzip.onfile = (file) => {
+      if (!isXmlEntry(file.name)) {
+        return; // not started → never decompressed
+      }
+      const chunks: Uint8Array[] = [];
+      file.ondata = (error, chunk, final) => {
+        if (error) {
+          fail(error);
+          return;
+        }
+        if (chunk.length) {
+          chunks.push(chunk);
+        }
+        if (final) {
+          const target = path.join(destDir, file.name);
+          if (path.relative(destDir, target).startsWith("..")) {
+            fail(new Error(`Unsafe archive entry path: ${file.name}`));
+            return;
+          }
+          writes.push(
+            mkdir(path.dirname(target), { recursive: true }).then(() => writeFile(target, concatChunks(chunks))),
+          );
+        }
+      };
+      file.start();
+    };
+
+    const stream = createReadStream(zipPath);
+    stream.on("data", (chunk) => {
+      if (failed) {
+        return;
+      }
+      try {
+        unzip.push(chunk as Uint8Array, false);
+      } catch (error) {
+        fail(error);
+      }
+    });
+    stream.on("error", fail);
+    stream.on("end", () => {
+      if (failed) {
+        return;
+      }
+      try {
+        unzip.push(new Uint8Array(0), true);
+      } catch (error) {
+        fail(error);
+        return;
+      }
+      Promise.all(writes)
+        .then(() => resolve())
+        .catch(fail);
+    });
+  });
+}
+
+function rebasePath(filePath: string | undefined, fromRoot: string, toRoot: string): string | undefined {
+  if (filePath === undefined) {
+    return undefined;
+  }
+  const relative = path.relative(fromRoot, filePath);
+  return relative.startsWith("..") ? filePath : path.join(toRoot, relative);
+}
+
+/** Re-anchor reported paths from the ephemeral temp tree to the package's real path. */
+function rebaseResult(
+  result: QtiPackageValidationResult,
+  fromRoot: string,
+  toRoot: string,
+): QtiPackageValidationResult {
+  const manifestPath = rebasePath(result.manifestPath, fromRoot, toRoot);
+  return {
+    ...result,
+    packagePath: toRoot,
+    ...(manifestPath !== undefined ? { manifestPath } : {}),
+    ...(result.manifestValidation
+      ? {
+          manifestValidation: {
+            ...result.manifestValidation,
+            filePath:
+              rebasePath(result.manifestValidation.filePath, fromRoot, toRoot) ?? result.manifestValidation.filePath,
+          },
+        }
+      : {}),
+    referencedDocumentResults: result.referencedDocumentResults.map((document) => ({
+      ...document,
+      filePath: rebasePath(document.filePath, fromRoot, toRoot) ?? document.filePath,
+    })),
+  };
+}
+
+/**
+ * Validate a QTI 3 content package held entirely in memory as PIF (Package Interchange
+ * Format) ZIP bytes. Only `.xml` entries are decompressed (media is skipped), but the
+ * caller's full byte buffer is still resident — suitable for modest packages and
+ * callers that already hold the bytes (tests, small authored packages). For
+ * potentially large packages prefer `validateQtiPackagePath`, which streams from disk.
+ *
+ * xi:include across archive entries is not resolved on this in-memory path (the
+ * resolver reads from the filesystem); `validateQtiPackagePath` resolves them.
+ */
+export async function validateQtiPackageArchive(
+  zipBytes: Uint8Array,
+  options?: { readonly reportPath?: string },
+): Promise<QtiPackageValidationResult> {
+  const reportPath = options?.reportPath ?? "qti-package.zip";
+
+  if (!isZipArchive(zipBytes)) {
+    return {
+      packagePath: reportPath,
+      status: "unsupported",
+      issues: [{ path: "$", message: "Package bytes are not a ZIP archive (missing the PK signature)." }],
+      referencedDocumentResults: [],
+    };
+  }
+
+  let entries: Record<string, Uint8Array>;
+  try {
+    entries = unzipSync(zipBytes, { filter: (file) => isXmlEntry(file.name) });
+  } catch (error) {
+    return {
+      packagePath: reportPath,
+      status: "unsupported",
+      issues: [
+        {
+          path: "$",
+          message: `Could not read the ZIP archive: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      referencedDocumentResults: [],
+    };
+  }
+
+  const decoder = new TextDecoder();
+  const source: PackageSource = {
+    reportPath,
+    async readManifest() {
+      const entry = entries["imsmanifest.xml"];
+      return entry ? { xml: decoder.decode(entry), sourcePath: path.join(reportPath, "imsmanifest.xml") } : null;
+    },
+    async readReferenced(href) {
+      const entry = entries[zipEntryKey(href)];
+      return entry ? { xml: decoder.decode(entry), sourcePath: path.join(reportPath, href) } : null;
+    },
+  };
+
+  return validatePackage(source);
+}
+
+/**
+ * Validate a QTI 3 content package at a filesystem path: an exploded directory, or a
+ * PIF ZIP file. The ZIP route streams from disk, materializing only the package's XML
+ * into a temporary directory (media is never inflated, so memory stays bounded for
+ * large packages), then validates the exploded tree — which also resolves xi:include
+ * across entries — and cleans the temp directory up afterwards.
+ */
+export async function validateQtiPackagePath(packagePath: string): Promise<QtiPackageValidationResult> {
+  const absolutePackagePath = path.resolve(packagePath);
+  const pathStat = await stat(absolutePackagePath);
+
+  if (pathStat.isDirectory()) {
+    return validatePackage(directorySource(absolutePackagePath));
+  }
+
+  const tempRoot = await mkdtemp(path.join(tmpdir(), "qti-pif-"));
+  try {
+    try {
+      await extractXmlEntriesToDir(absolutePackagePath, tempRoot);
+    } catch (error) {
+      return {
+        packagePath: absolutePackagePath,
+        status: "unsupported",
+        issues: [
+          {
+            path: "$",
+            message: `Could not read the package archive: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        referencedDocumentResults: [],
+      };
+    }
+
+    const result = await validatePackage(directorySource(tempRoot));
+    return rebaseResult(result, tempRoot, absolutePackagePath);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}

package/src/validate.ts

@@ -0,0 +1,118 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { normalizeQtiDocument } from "./normalize";
+import { parseXmlDocument } from "./parse-xml";
+import { detectQtiRoot } from "./root-detection";
+import { isNormalizationImplemented, selectQtiSchema } from "./schema-selection";
+import type { QtiValidationIssue, QtiValidationResult } from "./types";
+import { resolveXIncludes } from "./xinclude";
+
+type SafeParseResult = {
+  success: boolean;
+  error?: { issues?: Array<{ path?: PropertyKey[]; message?: string }> };
+};
+
+function formatIssuePath(pathEntries: PropertyKey[] | undefined): string {
+  if (!pathEntries?.length) {
+    return "$";
+  }
+
+  return `$${pathEntries.map((entry) => (typeof entry === "number" ? `[${entry}]` : `.${String(entry)}`)).join("")}`;
+}
+
+function flattenIssues(
+  error: { issues?: Array<{ path?: PropertyKey[]; message?: string }> } | undefined,
+): QtiValidationIssue[] {
+  return (error?.issues ?? []).map((issue) => ({
+    path: formatIssuePath(issue.path),
+    message: issue.message ?? "Validation error.",
+  }));
+}
+
+export async function validateQtiXmlFile(filePath: string): Promise<QtiValidationResult> {
+  const absolutePath = path.resolve(filePath);
+  const xml = await readFile(absolutePath, "utf8");
+
+  return validateQtiXmlContent(xml, { sourcePath: absolutePath });
+}
+
+/**
+ * Validate an in-memory XML instance (e.g. a serialized assessmentResult on its way
+ * out — the export-conformance round trip). `sourcePath` anchors relative xi:include
+ * hrefs and the reported `filePath`; in-memory instances default to the cwd.
+ */
+export async function validateQtiXmlContent(
+  xml: string,
+  options?: { readonly sourcePath?: string },
+): Promise<QtiValidationResult> {
+  const absolutePath = path.resolve(options?.sourcePath ?? "qti-content.xml");
+  const rootDetection = detectQtiRoot(xml);
+
+  if (!rootDetection) {
+    return {
+      filePath: absolutePath,
+      status: "unsupported",
+      issues: [{ path: "$", message: "Could not detect an XML root element." }],
+    };
+  }
+
+  const schemaSelection = selectQtiSchema(rootDetection);
+  if (!schemaSelection) {
+    return {
+      filePath: absolutePath,
+      rootDetection,
+      status: "unsupported",
+      issues: [{ path: "$", message: "No contracts schema is registered for this QTI root." }],
+    };
+  }
+
+  if (!isNormalizationImplemented(schemaSelection.version, schemaSelection.key)) {
+    return {
+      filePath: absolutePath,
+      rootDetection,
+      schemaSelectionKey: schemaSelection.key,
+      status: "unsupported",
+      issues: [{ path: "$", message: "XML normalization is not implemented for this QTI root yet." }],
+    };
+  }
+
+  let normalizedDocument: unknown;
+  try {
+    const documentRoot = parseXmlDocument(xml);
+
+    // Shared fragments (xi:include) splice in before normalization — this is the only
+    // layer that knows the file path the hrefs are relative to.
+    await resolveXIncludes(documentRoot, absolutePath);
+    normalizedDocument = normalizeQtiDocument(schemaSelection.version, schemaSelection.key, documentRoot);
+  } catch (error) {
+    return {
+      filePath: absolutePath,
+      rootDetection,
+      schemaSelectionKey: schemaSelection.key,
+      status: "parse-error",
+      issues: [{ path: "$", message: error instanceof Error ? error.message : String(error) }],
+    };
+  }
+
+  const parsed = schemaSelection.schema.safeParse(normalizedDocument) as SafeParseResult;
+  if (!parsed.success) {
+    return {
+      filePath: absolutePath,
+      rootDetection,
+      schemaSelectionKey: schemaSelection.key,
+      normalizedDocument,
+      status: "invalid",
+      issues: flattenIssues(parsed.error),
+    };
+  }
+
+  return {
+    filePath: absolutePath,
+    rootDetection,
+    schemaSelectionKey: schemaSelection.key,
+    normalizedDocument,
+    status: "valid",
+    issues: [],
+  };
+}

package/src/xinclude.ts

@@ -0,0 +1,92 @@
+/**
+ * XInclude resolution: `xi:include` elements splice their target's root element (or
+ * text, for parse="text") into the including document before normalization, resolving
+ * hrefs relative to each including file. Recursion is cycle-guarded; a failed include
+ * uses its `xi:fallback` children when present and otherwise fails loudly — the
+ * corpus's shared-fragment items depend on this happening at the file boundary, the
+ * only layer that knows the path.
+ */
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { parseXmlDocument, type QtiXmlElementNode, type QtiXmlNode } from "./parse-xml";
+
+const xincludeNamespace = "http://www.w3.org/2001/XInclude";
+
+function isXinclude(element: QtiXmlElementNode, localName: string): boolean {
+  return element.localName === localName && (element.namespaceUri === xincludeNamespace || element.prefix === "xi");
+}
+
+async function resolveInclude(
+  include: QtiXmlElementNode,
+  baseFilePath: string,
+  stack: string[],
+): Promise<QtiXmlNode[]> {
+  const href = include.attributes["href"];
+
+  if (href === undefined || href === "") {
+    throw new Error("<xi:include> requires an href.");
+  }
+
+  const targetPath = path.resolve(path.dirname(baseFilePath), href);
+
+  if (stack.includes(targetPath)) {
+    throw new Error(`XInclude cycle detected at ${href} (${[...stack, targetPath].join(" -> ")}).`);
+  }
+
+  let content: string;
+
+  try {
+    content = await readFile(targetPath, "utf8");
+  } catch (error) {
+    const fallback = include.children.find(
+      (child): child is QtiXmlElementNode => child.type === "element" && isXinclude(child, "fallback"),
+    );
+
+    if (fallback) {
+      // Fallback children may themselves contain includes, relative to this file.
+      await resolveChildren(fallback, baseFilePath, stack);
+
+      return fallback.children;
+    }
+
+    throw new Error(
+      `XInclude target "${href}" could not be read: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (include.attributes["parse"] === "text") {
+    return [{ type: "text", value: content }];
+  }
+
+  const fragmentRoot = parseXmlDocument(content);
+
+  await resolveChildren(fragmentRoot, targetPath, [...stack, targetPath]);
+
+  return [fragmentRoot];
+}
+
+async function resolveChildren(element: QtiXmlElementNode, baseFilePath: string, stack: string[]): Promise<void> {
+  const resolved: QtiXmlNode[] = [];
+
+  for (const child of element.children) {
+    if (child.type === "element") {
+      if (isXinclude(child, "include")) {
+        resolved.push(...(await resolveInclude(child, baseFilePath, stack)));
+        continue;
+      }
+
+      await resolveChildren(child, baseFilePath, stack);
+    }
+
+    resolved.push(child);
+  }
+
+  element.children = resolved;
+}
+
+/** Resolve every `xi:include` under `root` in place, relative to the document's file. */
+export async function resolveXIncludes(root: QtiXmlElementNode, filePath: string): Promise<void> {
+  await resolveChildren(root, filePath, [path.resolve(filePath)]);
+}

package/src/xml-writer.ts

@@ -0,0 +1,68 @@
+/**
+ * A tiny indenting XML writer shared by the binding serializers (results, usage
+ * data, AfA PNP). The XSDs' sequences dictate emit order; escaping covers text
+ * content and attribute values.
+ */
+
+export function escapeText(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function escapeAttribute(value: string): string {
+  return escapeText(value).replaceAll('"', "&quot;");
+}
+
+export type AttributeValue = string | number | boolean | undefined;
+
+function openTag(
+  name: string,
+  attributes: ReadonlyArray<readonly [string, AttributeValue]>,
+  selfClose: boolean,
+): string {
+  const rendered = attributes
+    .filter((entry): entry is readonly [string, string | number | boolean] => entry[1] !== undefined)
+    .map(([attribute, value]) => ` ${attribute}="${escapeAttribute(String(value))}"`)
+    .join("");
+
+  return `<${name}${rendered}${selfClose ? "/" : ""}>`;
+}
+
+export class XmlWriter {
+  private readonly lines: string[] = [];
+  private depth = 0;
+
+  line(text: string): void {
+    this.lines.push(`${"    ".repeat(this.depth)}${text}`);
+  }
+
+  /** Emit an escaped text fragment of mixed content on its own indented line. */
+  text(value: string): void {
+    this.line(escapeText(value));
+  }
+
+  element(
+    name: string,
+    attributes: ReadonlyArray<readonly [string, AttributeValue]>,
+    body?: (() => void) | string,
+  ): void {
+    if (body === undefined) {
+      this.line(openTag(name, attributes, true));
+      return;
+    }
+
+    if (typeof body === "string") {
+      this.line(`${openTag(name, attributes, false)}${escapeText(body)}</${name}>`);
+      return;
+    }
+
+    this.line(openTag(name, attributes, false));
+    this.depth += 1;
+    body();
+    this.depth -= 1;
+    this.line(`</${name}>`);
+  }
+
+  toString(): string {
+    return `${this.lines.join("\n")}\n`;
+  }
+}