@conform-ed/qti-xml 0.0.16

package/dist/normalize.d.ts

@@ -0,0 +1,3 @@
+import type { QtiXmlElementNode } from "./parse-xml";
+import type { QtiSchemaSelectionKey, QtiVersion } from "./types";
+export declare function normalizeQtiDocument(version: QtiVersion, schemaSelectionKey: QtiSchemaSelectionKey, root: QtiXmlElementNode): unknown;

package/dist/parse-xml.d.ts

@@ -0,0 +1,15 @@
+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;
+export declare function parseXmlDocument(xml: string): QtiXmlElementNode;

package/dist/root-detection.d.ts

@@ -0,0 +1,2 @@
+import type { QtiRootDetection } from "./types";
+export declare function detectQtiRoot(xml: string): QtiRootDetection | undefined;

package/dist/schema-selection.d.ts

@@ -0,0 +1,12 @@
+import type { QtiRootDetection, QtiSchemaSelectionKey, QtiVersion } from "./types";
+type SafeParseSchema = {
+    safeParse(input: unknown): unknown;
+};
+export interface QtiSchemaSelection {
+    version: QtiVersion;
+    key: QtiSchemaSelectionKey;
+    schema: SafeParseSchema;
+}
+export declare function isNormalizationImplemented(version: QtiVersion, key: QtiSchemaSelectionKey): boolean;
+export declare function selectQtiSchema(rootDetection: QtiRootDetection): QtiSchemaSelection | undefined;
+export {};

package/dist/serialize-asi.d.ts

@@ -0,0 +1,30 @@
+/**
+ * QTI 3 ASI (Assessment, Section & Item) XML serialization — the authoring-system
+ * EXPORT direction. Takes the normalized/contracts document shape and emits an
+ * instance against the official ASI binding (namespace imsqtiasi_v3p0), the exact
+ * inverse of the normalizer in normalize.ts. The export-conformance gate is the model
+ * round trip (serialize → parse → normalize → strict contracts schema → deep-equal),
+ * proven across the whole vendored corpus in serialize-asi-corpus.local.test.ts.
+ *
+ * Element/attribute spellings mirror the normalizer's reads exactly (kebab-case in the
+ * XSD, e.g. `qti-hottext` not `qti-hot-text`, `base-type`, `response-identifier`). The
+ * normalizer is lossy in known ways — element @id, comments, the optional
+ * <qti-content-body> wrapper, the item-ref/section-ref distinction for bare refs — and
+ * those losses are exactly what this writer need not reproduce: re-normalization drops
+ * the same nothing, so model idempotence holds.
+ */
+export declare const asiNamespace = "http://www.imsglobal.org/xsd/imsqtiasi_v3p0";
+/** Serialize a qti-assessment-item document against the ASI binding. */
+export declare function serializeQtiAssessmentItem(document: unknown): string;
+/** Serialize a qti-assessment-stimulus document against the ASI binding. */
+export declare function serializeQtiAssessmentStimulus(document: unknown): string;
+/** Serialize a qti-assessment-test document against the ASI binding. */
+export declare function serializeQtiAssessmentTest(document: unknown): string;
+/** Serialize a standalone qti-assessment-section document. */
+export declare function serializeQtiAssessmentSection(document: unknown): string;
+/** Serialize a standalone qti-response-processing document (best-practice templates). */
+export declare function serializeQtiResponseProcessingDocument(document: unknown): string;
+/** Serialize a standalone qti-outcome-declaration document. */
+export declare function serializeQtiOutcomeDeclarationDocument(document: unknown): string;
+/** Serialize a standalone qti-outcome-processing document. */
+export declare function serializeQtiOutcomeProcessingDocument(document: unknown): string;

package/dist/serialize-document.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Universal QTI serialization dispatch: given a (version, schema-selection-key) and a
+ * normalized document, emit the spec-valid XML instance against the matching binding.
+ * The inverse of normalizeQtiDocument — delegating to the per-binding serializers
+ * (ASI, manifest, results, usage data, PNP), each gated by its own export round trip.
+ */
+import type { QtiSchemaSelectionKey, QtiVersion } from "./types";
+/** Roots with a serializer registered (the export-conformant direction). */
+export declare function isSerializationImplemented(version: QtiVersion, key: QtiSchemaSelectionKey): boolean;
+export declare function serializeQtiDocument(version: QtiVersion, key: QtiSchemaSelectionKey, document: unknown): string;

package/dist/serialize-manifest.d.ts

@@ -0,0 +1,11 @@
+/**
+ * QTI 3 content-package manifest + qtiMetadata XML serialization — the export
+ * direction of the packaging binding (imscp_v1p1) and the metadata binding
+ * (imsqti_metadata_v3p0). Inverse of normalizeQti301Manifest / mapV3QtiMetadata;
+ * IEEE LOM rides through as a structurally preserved foreign-XML node. Gated by the
+ * corpus model round trip.
+ */
+/** Serialize a standalone qtiMetadata document. */
+export declare function serializeQtiMetadata(document: unknown): string;
+/** Serialize a QTI 3 content-package manifest. */
+export declare function serializeQtiManifest(document: unknown): string;

package/dist/serialize-pnp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AfA PNP (QTI 3.0 profile) XML serialization (imsqtiv3p0_afa3p0pnp_v1p0) — the
+ * export direction of the candidate-preferences binding, the exact inverse of the
+ * import normalizer; gated in tests by the round trip through our own parser,
+ * normalizer, and strict contracts schema.
+ */
+import type { QtiAccessForAllPnpDocument, QtiAccessForAllPnpRecordsDocument } from "@conform-ed/contracts/qti/v3_0_1";
+/** Serialize a candidate-preferences document against the official QTI 3 profile binding. */
+export declare function serializeQtiAccessForAllPnp(document: QtiAccessForAllPnpDocument): string;
+/** Serialize a person-keyed PNP records document. */
+export declare function serializeQtiAccessForAllPnpRecords(document: QtiAccessForAllPnpRecordsDocument): string;

package/dist/serialize-result.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 } from "@conform-ed/contracts/qti/v3_0_1";
+/** Serialize a results document against the official 3.0 binding. */
+export declare function serializeQtiAssessmentResult(document: QtiAssessmentResultDocument): string;

package/dist/serialize-usage-data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 } from "@conform-ed/contracts/qti/v3_0_1";
+/** Serialize a usage data document against the official 3.0 binding. */
+export declare function serializeQtiUsageData(document: QtiUsageDataDocument): string;

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+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[];
+}

package/dist/validate-package.d.ts

@@ -0,0 +1,30 @@
+import type { QtiValidationIssue, QtiValidationResult } from "./types";
+export interface QtiPackageValidationResult {
+    packagePath: string;
+    manifestPath?: string;
+    status: "invalid" | "unsupported" | "valid";
+    issues: QtiValidationIssue[];
+    manifestValidation?: QtiValidationResult;
+    referencedDocumentResults: QtiValidationResult[];
+}
+/**
+ * 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 declare function validateQtiPackageArchive(zipBytes: Uint8Array, options?: {
+    readonly reportPath?: string;
+}): Promise<QtiPackageValidationResult>;
+/**
+ * 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 declare function validateQtiPackagePath(packagePath: string): Promise<QtiPackageValidationResult>;

package/dist/validate.d.ts

@@ -0,0 +1,10 @@
+import type { QtiValidationResult } from "./types";
+export declare function validateQtiXmlFile(filePath: string): Promise<QtiValidationResult>;
+/**
+ * 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 declare function validateQtiXmlContent(xml: string, options?: {
+    readonly sourcePath?: string;
+}): Promise<QtiValidationResult>;

package/dist/xinclude.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { type QtiXmlElementNode } from "./parse-xml";
+/** Resolve every `xi:include` under `root` in place, relative to the document's file. */
+export declare function resolveXIncludes(root: QtiXmlElementNode, filePath: string): Promise<void>;

package/dist/xml-writer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare function escapeText(value: string): string;
+export declare function escapeAttribute(value: string): string;
+export type AttributeValue = string | number | boolean | undefined;
+export declare class XmlWriter {
+    private readonly lines;
+    private depth;
+    line(text: string): void;
+    /** Emit an escaped text fragment of mixed content on its own indented line. */
+    text(value: string): void;
+    element(name: string, attributes: ReadonlyArray<readonly [string, AttributeValue]>, body?: (() => void) | string): void;
+    toString(): string;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@conform-ed/qti-xml",
+  "version": "0.0.16",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --format esm --target node --external @conform-ed/contracts --external fast-xml-parser --external fast-xml-validator --external fflate && tsgo -p tsconfig.build.json",
+    "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
+    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "test": "bun test",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@conform-ed/contracts": "0.0.16",
+    "fast-xml-parser": "^5.3.1",
+    "fast-xml-validator": "^1.1.1",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "xmllint-wasm": "^5.2.0"
+  }
+}

package/src/example-inventory.ts

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { SyntaxValidator } from "fast-xml-validator";
+
+import { detectQtiRoot } from "./root-detection";
+import { isNormalizationImplemented, selectQtiSchema } from "./schema-selection";
+import type {
+  QtiExampleInventoryEntry,
+  QtiExampleInventoryReport,
+  QtiFileKind,
+  QtiSupportStatus,
+  QtiXmlStatus,
+} from "./types";
+
+const knownBrokenExampleSuffixes = ["qtiv3-examples/CAT/test.xml", "qtiv3-examples/results/full-example.xml"] as const;
+
+function createEmptyCountRecord<T extends string>(keys: readonly T[]): Record<T, number> {
+  return Object.fromEntries(keys.map((key) => [key, 0])) as Record<T, number>;
+}
+
+async function walkFiles(rootPath: string): Promise<string[]> {
+  const entries = await readdir(rootPath, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+
+    const absolutePath = path.join(rootPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(absolutePath)));
+      continue;
+    }
+
+    files.push(absolutePath);
+  }
+
+  return files;
+}
+
+function normalizeRelativePath(rootPath: string, absolutePath: string): string {
+  return path.relative(rootPath, absolutePath).split(path.sep).join("/");
+}
+
+function fileKindForPath(filePath: string): QtiFileKind {
+  const extension = path.extname(filePath).toLowerCase();
+
+  switch (extension) {
+    case ".xml":
+      return "xml";
+    case ".zip":
+      return "zip";
+    case ".html":
+    case ".htm":
+      return "html";
+    default:
+      return "other";
+  }
+}
+
+function isKnownBrokenExample(relativePath: string): boolean {
+  return knownBrokenExampleSuffixes.some((suffix) => relativePath === suffix || relativePath.endsWith(`/${suffix}`));
+}
+
+function xmlStatusForContent(fileKind: QtiFileKind, content: string): QtiXmlStatus {
+  if (fileKind !== "xml") {
+    return "not-xml";
+  }
+
+  return SyntaxValidator.validate(content) === true ? "well-formed" : "malformed";
+}
+
+function supportStatusForEntry(entry: {
+  fileKind: QtiFileKind;
+  xmlStatus: QtiXmlStatus;
+  relativePath: string;
+  hasSchema: boolean;
+  hasNormalizer: boolean;
+}): { status: QtiSupportStatus; note?: string } {
+  if (entry.fileKind === "zip") {
+    return { status: "zip-package" };
+  }
+
+  if (entry.fileKind !== "xml") {
+    return { status: "not-xml" };
+  }
+
+  if (isKnownBrokenExample(entry.relativePath)) {
+    return {
+      status: "known-broken-example",
+      note:
+        entry.xmlStatus === "malformed"
+          ? "Known malformed official example."
+          : "Known official example path that does not currently contain a usable QTI XML document.",
+    };
+  }
+
+  if (entry.xmlStatus === "malformed") {
+    return { status: "unsupported-root", note: "XML is not well formed." };
+  }
+
+  if (!entry.hasSchema) {
+    return { status: "unsupported-root", note: "No contracts schema is registered for this root." };
+  }
+
+  if (!entry.hasNormalizer) {
+    return {
+      status: "unsupported-normalization",
+      note: "A contracts schema exists, but XML normalization is not implemented yet.",
+    };
+  }
+
+  return { status: "supported" };
+}
+
+function hashContent(content: string): string {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+export async function buildQtiExampleInventory(rootPath: string): Promise<QtiExampleInventoryReport> {
+  const absoluteRootPath = path.resolve(rootPath);
+  const filePaths = (await walkFiles(absoluteRootPath)).sort();
+  const entries: QtiExampleInventoryEntry[] = [];
+
+  for (const absolutePath of filePaths) {
+    const relativePath = normalizeRelativePath(absoluteRootPath, absolutePath);
+    const fileKind = fileKindForPath(absolutePath);
+    const sourceGroup = relativePath.split("/", 1)[0] ?? ".";
+    const content = fileKind === "zip" ? "" : await readFile(absolutePath, "utf8");
+    const contentHash = hashContent(content);
+    const xmlStatus = xmlStatusForContent(fileKind, content);
+    const rootDetection = fileKind === "xml" ? detectQtiRoot(content) : undefined;
+    const schemaSelection = rootDetection ? selectQtiSchema(rootDetection) : undefined;
+    const support = supportStatusForEntry({
+      fileKind,
+      xmlStatus,
+      relativePath,
+      hasSchema: Boolean(schemaSelection),
+      hasNormalizer:
+        schemaSelection !== undefined && isNormalizationImplemented(schemaSelection.version, schemaSelection.key),
+    });
+
+    entries.push({
+      absolutePath,
+      relativePath,
+      sourceGroup,
+      fileKind,
+      xmlStatus,
+      supportStatus: support.status,
+      contentHash,
+      ...(rootDetection?.rootName ? { rootName: rootDetection.rootName } : {}),
+      ...(rootDetection?.localName ? { localName: rootDetection.localName } : {}),
+      ...(rootDetection?.namespaceUri ? { namespaceUri: rootDetection.namespaceUri } : {}),
+      ...(rootDetection?.inferredVersion ? { inferredVersion: rootDetection.inferredVersion } : {}),
+      ...(rootDetection?.schemaSelectionKey ? { schemaSelectionKey: rootDetection.schemaSelectionKey } : {}),
+      ...(support.note ? { note: support.note } : {}),
+    });
+  }
+
+  const byFileKind = createEmptyCountRecord(["html", "other", "xml", "zip"] as const);
+  const bySupportStatus = createEmptyCountRecord([
+    "known-broken-example",
+    "not-xml",
+    "supported",
+    "unsupported-normalization",
+    "unsupported-root",
+    "zip-package",
+  ] as const);
+  const byVersion: Record<string, number> = {};
+
+  for (const entry of entries) {
+    byFileKind[entry.fileKind] += 1;
+    bySupportStatus[entry.supportStatus] += 1;
+
+    if (entry.inferredVersion) {
+      byVersion[entry.inferredVersion] = (byVersion[entry.inferredVersion] ?? 0) + 1;
+    }
+  }
+
+  return {
+    rootPath: absoluteRootPath,
+    generatedAt: new Date().toISOString(),
+    entries,
+    summary: {
+      totalFiles: entries.length,
+      byFileKind,
+      bySupportStatus,
+      byVersion,
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./example-inventory";
+export * from "./normalize";
+export * from "./parse-xml";
+export * from "./root-detection";
+export * from "./schema-selection";
+export * from "./types";
+export * from "./validate";
+export * from "./validate-package";
+export * from "./serialize-result";
+export * from "./serialize-pnp";
+export * from "./serialize-usage-data";
+export * from "./serialize-asi";
+export * from "./serialize-manifest";
+export * from "./serialize-document";