@longsightgroup/qti3-core 0.9.3 → 0.9.4

package/src/qti-package-types.ts

@@ -0,0 +1,117 @@
+import type { QtiDiagnostic, QtiDocument } from "./types.js";
+
+export type {
+  QtiPackageInflateContext,
+  QtiPackageInflateRaw,
+  QtiPackageParseOptions,
+} from "./qti-package-zip.js";
+
+/** Neutral package shape detected from IMS manifest resources. */
+export type QtiPackageShape = "manifest-item-resources" | "assessment-test-resource" | "unknown";
+
+/** Origin of an assessment item inside a parsed QTI package. */
+export type QtiPackageItemSource = "manifest" | "assessment-test";
+
+/** Source of a package-local asset reference. */
+export type QtiPackageAssetSource =
+  | "manifest-resource"
+  | "item-content"
+  | "assessment-test-content";
+
+/** Parsed package manifest file entry. */
+export interface QtiManifestFile {
+  readonly href: string;
+  readonly attributes: Record<string, string>;
+}
+
+/** Parsed package manifest resource entry. */
+export interface QtiManifestResource {
+  readonly identifier: string;
+  readonly type: string;
+  readonly href?: string | undefined;
+  readonly files: readonly QtiManifestFile[];
+  readonly dependencies: readonly string[];
+  readonly attributes: Record<string, string>;
+}
+
+/** Parsed timing metadata from item or assessment-test XML. */
+export interface QtiTimingMetadata {
+  readonly sourcePath: string;
+  readonly timeDependent?: boolean | undefined;
+  readonly minTime?: string | undefined;
+  readonly maxTime?: string | undefined;
+  readonly allowLateSubmission?: boolean | undefined;
+  readonly attributes: Record<string, string>;
+}
+
+/** Neutral standard-alignment metadata discovered in package XML. */
+export interface QtiStandardAlignment {
+  readonly sourcePath: string;
+  readonly qtiName: string;
+  readonly identifier?: string | undefined;
+  readonly framework?: string | undefined;
+  readonly targetName?: string | undefined;
+  readonly targetUrl?: string | undefined;
+  readonly text?: string | undefined;
+  readonly attributes: Record<string, string>;
+}
+
+/** Assessment item reference from an assessment-test package. */
+export interface QtiAssessmentTestItemRef {
+  readonly identifier?: string | undefined;
+  readonly href: string;
+  readonly attributes: Record<string, string>;
+}
+
+/** Parsed assessment-test resource model for package-level importers. */
+export interface QtiAssessmentTestPackageModel {
+  readonly href: string;
+  readonly identifier: string;
+  readonly title?: string | undefined;
+  readonly manifestResourceIdentifier?: string | undefined;
+  readonly itemRefs: readonly QtiAssessmentTestItemRef[];
+  readonly timing?: QtiTimingMetadata | undefined;
+  readonly standards: readonly QtiStandardAlignment[];
+  readonly assetHrefs: readonly string[];
+  readonly diagnostics: readonly QtiDiagnostic[];
+  readonly attributes: Record<string, string>;
+  readonly xml: string;
+}
+
+/** Parsed assessment item model inside a QTI package. */
+export interface QtiPackageItem {
+  readonly href: string;
+  readonly source: QtiPackageItemSource;
+  readonly manifestResourceIdentifier?: string | undefined;
+  readonly assessmentItemRefIdentifier?: string | undefined;
+  readonly identifier?: string | undefined;
+  readonly title?: string | undefined;
+  readonly document?: QtiDocument | undefined;
+  readonly timing?: QtiTimingMetadata | undefined;
+  readonly standards: readonly QtiStandardAlignment[];
+  readonly assetHrefs: readonly string[];
+  readonly diagnostics: readonly QtiDiagnostic[];
+  readonly xml: string;
+}
+
+/** Package-local asset discovered from manifest files or XML content references. */
+export interface QtiPackageAsset {
+  readonly href: string;
+  readonly mediaType?: string | undefined;
+  readonly source: QtiPackageAssetSource;
+  readonly referencedBy: readonly string[];
+}
+
+/** Parsed QTI package manifest/resource graph and item/test projection. */
+export interface QtiPackageParseResult {
+  readonly ok: boolean;
+  readonly title: string;
+  readonly packageShape: QtiPackageShape;
+  readonly items: readonly QtiPackageItem[];
+  readonly assets: readonly QtiPackageAsset[];
+  readonly manifestResources: readonly QtiManifestResource[];
+  readonly assessmentTest?: QtiAssessmentTestPackageModel | undefined;
+  readonly timing?: QtiTimingMetadata | undefined;
+  readonly standards: readonly QtiStandardAlignment[];
+  readonly diagnostics: readonly QtiDiagnostic[];
+}

package/src/qti-package-xml.ts

@@ -0,0 +1,97 @@
+import { parseQtiPackageXmlTree, type QtiPackageXmlNode } from "./package-xml.js";
+import { normalizePackagePath, pushPackageDiagnostic } from "./qti-package-paths.js";
+import { decodeUtf8, type QtiPackageEntry } from "./qti-package-zip.js";
+import type { QtiDiagnostic } from "./types.js";
+
+/** Parsed package XML file with lightweight tree and source text. */
+export interface PackageXmlFile {
+  readonly path: string;
+  readonly xml: string;
+  readonly root?: QtiPackageXmlNode | undefined;
+  readonly errors: readonly string[];
+}
+
+export function parseXmlFiles(
+  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+): Map<string, PackageXmlFile> {
+  const xmlFiles = new Map<string, PackageXmlFile>();
+  for (const entry of entriesByPath.values()) {
+    if (!entry.path.toLowerCase().endsWith(".xml")) continue;
+    xmlFiles.set(entry.path, parsePackageXml(entry));
+  }
+  return xmlFiles;
+}
+
+export function parsePackageXml(entry: QtiPackageEntry): PackageXmlFile {
+  const xml = decodeUtf8(entry.bytes);
+  const parsed = parseQtiPackageXmlTree(xml);
+  return {
+    path: entry.path,
+    xml,
+    root: parsed.root,
+    errors: parsed.errors,
+  };
+}
+
+export function pushXmlDiagnostics(xmlFile: PackageXmlFile, diagnostics: QtiDiagnostic[]): void {
+  for (const message of xmlFile.errors) {
+    pushPackageDiagnostic(diagnostics, "xml.parse", "error", message, xmlFile.path);
+  }
+}
+
+export function childPackageElements(
+  node: QtiPackageXmlNode,
+  localName?: string,
+): QtiPackageXmlNode[] {
+  return node.children.filter((child) => !localName || child.localName === localName);
+}
+
+export function packageDescendants(
+  node: QtiPackageXmlNode | undefined,
+  localName?: string,
+): QtiPackageXmlNode[] {
+  if (!node) return [];
+  const found: QtiPackageXmlNode[] = [];
+  for (const child of node.children) {
+    if (!localName || child.localName === localName) found.push(child);
+    found.push(...packageDescendants(child, localName));
+  }
+  return found;
+}
+
+export function resolvePackageHref(
+  from: string,
+  href: string,
+  diagnostics: QtiDiagnostic[],
+): string | undefined {
+  const strippedHref = stripHrefSuffix(href);
+  const base = from.includes("/") ? from.slice(0, from.lastIndexOf("/") + 1) : "";
+  return normalizePackagePath(`${base}${strippedHref}`, "package reference", diagnostics);
+}
+
+export function stripHrefSuffix(href: string): string {
+  return href.split(/[?#]/, 1)[0] ?? "";
+}
+
+export function isPackageRelativeHref(href: string | undefined): href is string {
+  const trimmed = href?.trim() ?? "";
+  if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("//")) return false;
+  return !/^[a-z][a-z0-9+.-]*:/i.test(trimmed);
+}
+
+export function joinPackagePath(packagePath: string, localPath: string): string {
+  return localPath.startsWith("/") ? `${packagePath}${localPath}` : `${packagePath}/${localPath}`;
+}
+
+export function scopeDiagnosticToPackagePath(
+  packagePath: string,
+  diagnostic: QtiDiagnostic,
+): QtiDiagnostic {
+  const localPath = diagnostic.path ?? diagnostic.source?.path;
+  const path = localPath ? joinPackagePath(packagePath, localPath) : packagePath;
+  return {
+    ...diagnostic,
+    path,
+    source: diagnostic.source ? { ...diagnostic.source, path } : diagnostic.source,
+  };
+}

package/src/qti-package-zip.ts

@@ -0,0 +1,325 @@
+import { normalizePackagePath, pushPackageDiagnostic } from "./qti-package-paths.js";
+import type { QtiDiagnostic } from "./types.js";
+
+/** Context passed to a caller-owned raw DEFLATE inflater. */
+export interface QtiPackageInflateContext {
+  readonly path: string;
+  readonly compressedSize: number;
+  readonly uncompressedSize: number;
+  readonly compressionMethod: number;
+}
+
+/** Optional raw DEFLATE inflater for ZIP entries compressed with method 8. */
+export type QtiPackageInflateRaw = (
+  bytes: Uint8Array,
+  context: QtiPackageInflateContext,
+) => Uint8Array;
+
+/** Options for parsing a QTI ZIP package. */
+export interface QtiPackageParseOptions {
+  readonly inflateRaw?: QtiPackageInflateRaw | undefined;
+}
+
+/** Decoded ZIP entry from a QTI package. */
+export interface QtiPackageEntry {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+}
+
+/** Read stored ZIP entries and optionally inflate raw DEFLATE entries through caller code. */
+export function readQtiPackageZipEntries(
+  bytes: Uint8Array,
+  options: QtiPackageParseOptions,
+  diagnostics: QtiDiagnostic[],
+): QtiPackageEntry[] {
+  try {
+    return readZipEntriesUnsafe(bytes, options, diagnostics);
+  } catch {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.zip.invalid",
+      "error",
+      "QTI package ZIP central directory is malformed.",
+    );
+    return [];
+  }
+}
+
+// Intentionally manual: core's TS lib is ES2023-only (no DOM/Node globals).
+// TextDecoder is available on all supported runtimes, but using it would require
+// widening lib, ambient types, or globalThis casts in this zero-runtime-dependency package.
+/** Decode UTF-8 package entry names and XML payloads. */
+export function decodeUtf8(bytes: Uint8Array): string {
+  const input =
+    bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf ? bytes.subarray(3) : bytes;
+  let text = "";
+
+  for (let index = 0; index < input.length; ) {
+    const first = input[index];
+    if (first === undefined) break;
+    if (first < 0x80) {
+      text += String.fromCharCode(first);
+      index += 1;
+      continue;
+    }
+
+    const decoded = decodeUtf8CodePoint(input, index);
+    text += String.fromCodePoint(decoded.codePoint);
+    index += decoded.length;
+  }
+
+  return text;
+}
+
+function readZipEntriesUnsafe(
+  bytes: Uint8Array,
+  options: QtiPackageParseOptions,
+  diagnostics: QtiDiagnostic[],
+): QtiPackageEntry[] {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const eocdOffset = findEndOfCentralDirectory(view);
+  if (eocdOffset < 0) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.zip.centralDirectory.missing",
+      "error",
+      "No ZIP central directory was found.",
+    );
+    return [];
+  }
+
+  const entryCount = view.getUint16(eocdOffset + 10, true);
+  let offset = view.getUint32(eocdOffset + 16, true);
+  const entries: QtiPackageEntry[] = [];
+
+  for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > view.byteLength) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.zip.centralDirectory.truncated",
+        "error",
+        "ZIP central directory ended before all entries could be read.",
+      );
+      break;
+    }
+
+    if (view.getUint32(offset, true) !== 0x02014b50) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.zip.centralDirectory.entry",
+        "error",
+        "ZIP central directory entry header is invalid.",
+      );
+      break;
+    }
+
+    const compressionMethod = view.getUint16(offset + 10, true);
+    const compressedSize = view.getUint32(offset + 20, true);
+    const uncompressedSize = view.getUint32(offset + 24, true);
+    const nameLength = view.getUint16(offset + 28, true);
+    const extraLength = view.getUint16(offset + 30, true);
+    const commentLength = view.getUint16(offset + 32, true);
+    const localHeaderOffset = view.getUint32(offset + 42, true);
+    const nameStart = offset + 46;
+    const nameEnd = nameStart + nameLength;
+    if (nameEnd > view.byteLength) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.zip.centralDirectory.name",
+        "error",
+        "ZIP central directory entry name is truncated.",
+      );
+      break;
+    }
+
+    const rawName = bytes.slice(nameStart, nameEnd);
+    const decodedName = decodeUtf8(rawName).replaceAll("\\", "/");
+    offset += 46 + nameLength + extraLength + commentLength;
+    if (decodedName.endsWith("/")) continue;
+
+    const path = normalizePackagePath(decodedName, "ZIP entry", diagnostics);
+    if (!path) continue;
+
+    const content = zipEntryBytes(
+      bytes,
+      view,
+      {
+        path,
+        compressedSize,
+        uncompressedSize,
+        compressionMethod,
+        localHeaderOffset,
+      },
+      options,
+      diagnostics,
+    );
+    if (content) entries.push({ path, bytes: content });
+  }
+
+  return entries;
+}
+
+function zipEntryBytes(
+  bytes: Uint8Array,
+  view: DataView,
+  entry: {
+    readonly path: string;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+    readonly compressionMethod: number;
+    readonly localHeaderOffset: number;
+  },
+  options: QtiPackageParseOptions,
+  diagnostics: QtiDiagnostic[],
+): Uint8Array | undefined {
+  if (entry.localHeaderOffset + 30 > view.byteLength) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.zip.localHeader.truncated",
+      "error",
+      `ZIP local header for ${entry.path} is truncated.`,
+      entry.path,
+    );
+    return undefined;
+  }
+
+  if (view.getUint32(entry.localHeaderOffset, true) !== 0x04034b50) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.zip.localHeader",
+      "error",
+      `ZIP local header for ${entry.path} is invalid.`,
+      entry.path,
+    );
+    return undefined;
+  }
+
+  const nameLength = view.getUint16(entry.localHeaderOffset + 26, true);
+  const extraLength = view.getUint16(entry.localHeaderOffset + 28, true);
+  const dataOffset = entry.localHeaderOffset + 30 + nameLength + extraLength;
+  const dataEnd = dataOffset + entry.compressedSize;
+  if (dataEnd > view.byteLength) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.zip.entry.truncated",
+      "error",
+      `ZIP entry ${entry.path} content is truncated.`,
+      entry.path,
+    );
+    return undefined;
+  }
+
+  const compressed = bytes.slice(dataOffset, dataEnd);
+  if (entry.compressionMethod === 0) return compressed;
+
+  if (entry.compressionMethod === 8) {
+    const inflateRaw = options.inflateRaw;
+    if (!inflateRaw) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.zip.entry.compression.unsupported",
+        "error",
+        `ZIP entry ${entry.path} uses DEFLATE compression, but no inflateRaw option was provided.`,
+        entry.path,
+      );
+      return undefined;
+    }
+
+    try {
+      return inflateRaw(compressed, {
+        path: entry.path,
+        compressedSize: entry.compressedSize,
+        uncompressedSize: entry.uncompressedSize,
+        compressionMethod: entry.compressionMethod,
+      });
+    } catch {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.zip.entry.inflate",
+        "error",
+        `ZIP entry ${entry.path} could not be inflated.`,
+        entry.path,
+      );
+      return undefined;
+    }
+  }
+
+  pushPackageDiagnostic(
+    diagnostics,
+    "package.zip.entry.compression.unsupported",
+    "error",
+    `ZIP entry ${entry.path} uses unsupported compression method ${entry.compressionMethod}.`,
+    entry.path,
+  );
+  return undefined;
+}
+
+function findEndOfCentralDirectory(view: DataView): number {
+  const minimumOffset = Math.max(0, view.byteLength - 65557);
+  for (let offset = view.byteLength - 22; offset >= minimumOffset; offset -= 1) {
+    if (view.getUint32(offset, true) === 0x06054b50) return offset;
+  }
+  return -1;
+}
+
+function decodeUtf8CodePoint(
+  bytes: Uint8Array,
+  index: number,
+): { readonly codePoint: number; readonly length: number } {
+  const first = bytes[index];
+  if (first === undefined) return { codePoint: 0xfffd, length: 1 };
+
+  if (first >= 0xc2 && first <= 0xdf) {
+    const second = bytes[index + 1];
+    if (isUtf8Continuation(second)) {
+      return {
+        codePoint: ((first & 0x1f) << 6) | (second & 0x3f),
+        length: 2,
+      };
+    }
+  }
+
+  if (first >= 0xe0 && first <= 0xef) {
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    if (
+      isUtf8Continuation(second) &&
+      isUtf8Continuation(third) &&
+      !(first === 0xe0 && second < 0xa0) &&
+      !(first === 0xed && second >= 0xa0)
+    ) {
+      return {
+        codePoint: ((first & 0x0f) << 12) | ((second & 0x3f) << 6) | (third & 0x3f),
+        length: 3,
+      };
+    }
+  }
+
+  if (first >= 0xf0 && first <= 0xf4) {
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    const fourth = bytes[index + 3];
+    if (
+      isUtf8Continuation(second) &&
+      isUtf8Continuation(third) &&
+      isUtf8Continuation(fourth) &&
+      !(first === 0xf0 && second < 0x90) &&
+      !(first === 0xf4 && second >= 0x90)
+    ) {
+      return {
+        codePoint:
+          ((first & 0x07) << 18) |
+          ((second & 0x3f) << 12) |
+          ((third & 0x3f) << 6) |
+          (fourth & 0x3f),
+        length: 4,
+      };
+    }
+  }
+
+  return { codePoint: 0xfffd, length: 1 };
+}
+
+function isUtf8Continuation(value: number | undefined): value is number {
+  return value !== undefined && value >= 0x80 && value <= 0xbf;
+}

package/src/qti-package.ts

@@ -0,0 +1,176 @@
+import { pushPackageDiagnostic } from "./qti-package-paths.js";
+import { collectPackageAssets } from "./qti-package-assets.js";
+import {
+  detectPackageShape,
+  diagnoseManifestDependencyReferences,
+  diagnosePrimaryResourceHrefs,
+  indexManifestResources,
+  isQtiAssessmentTestResource,
+  isQtiItemResource,
+  parseManifestResources,
+  QTI_PACKAGE_MANIFEST_PATH,
+} from "./qti-package-manifest.js";
+import {
+  itemReferencesForPackageShape,
+  parseAssessmentTestPackageModel,
+  parsePackageItems,
+} from "./qti-package-items.js";
+import {
+  packageTitle,
+  parseStandardAlignments,
+  primaryTiming,
+  uniqueStandards,
+} from "./qti-package-metadata.js";
+import type { QtiPackageParseResult } from "./qti-package-types.js";
+import { parseXmlFiles, pushXmlDiagnostics } from "./qti-package-xml.js";
+import {
+  readQtiPackageZipEntries,
+  type QtiPackageEntry,
+  type QtiPackageParseOptions,
+} from "./qti-package-zip.js";
+import type { QtiDiagnostic } from "./types.js";
+
+export type {
+  QtiAssessmentTestItemRef,
+  QtiAssessmentTestPackageModel,
+  QtiManifestFile,
+  QtiManifestResource,
+  QtiPackageAsset,
+  QtiPackageAssetSource,
+  QtiPackageItem,
+  QtiPackageItemSource,
+  QtiPackageParseResult,
+  QtiPackageShape,
+  QtiStandardAlignment,
+  QtiTimingMetadata,
+} from "./qti-package-types.js";
+
+export type {
+  QtiPackageInflateContext,
+  QtiPackageInflateRaw,
+  QtiPackageParseOptions,
+} from "./qti-package-zip.js";
+
+/** Parse a QTI ZIP package into a neutral manifest, item, asset, and diagnostic model. */
+export function parseQtiPackage(
+  bytes: Uint8Array,
+  options: QtiPackageParseOptions = {},
+): QtiPackageParseResult {
+  const diagnostics: QtiDiagnostic[] = [];
+  const entries = readQtiPackageZipEntries(bytes, options, diagnostics);
+  return parseQtiPackageEntries(entries, diagnostics);
+}
+
+function parseQtiPackageEntries(
+  entries: readonly QtiPackageEntry[],
+  diagnostics: QtiDiagnostic[],
+): QtiPackageParseResult {
+  const entriesByPath = indexEntries(entries, diagnostics);
+  const xmlFilesByPath = parseXmlFiles(entriesByPath);
+  const manifestXml = xmlFilesByPath.get(QTI_PACKAGE_MANIFEST_PATH);
+
+  if (!manifestXml) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.manifest.missing",
+      "error",
+      "QTI package does not contain imsmanifest.xml.",
+      QTI_PACKAGE_MANIFEST_PATH,
+    );
+  } else {
+    pushXmlDiagnostics(manifestXml, diagnostics);
+  }
+
+  const manifestRoot = manifestXml?.root?.localName === "manifest" ? manifestXml.root : undefined;
+  if (manifestXml?.root && !manifestRoot) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.manifest.root",
+      "error",
+      `Expected imsmanifest.xml root manifest, found ${manifestXml.root.localName}.`,
+      QTI_PACKAGE_MANIFEST_PATH,
+    );
+  }
+
+  const manifestResourceRecords = manifestRoot
+    ? parseManifestResources(manifestRoot, entriesByPath, diagnostics)
+    : [];
+  const manifestResources = manifestResourceRecords;
+  const resourcesByIdentifier = indexManifestResources(manifestResourceRecords, diagnostics);
+  diagnoseManifestDependencyReferences(manifestResourceRecords, resourcesByIdentifier, diagnostics);
+
+  const itemResources = manifestResourceRecords.filter((resource) =>
+    isQtiItemResource(resource.type),
+  );
+  const assessmentTestResources = manifestResourceRecords.filter((resource) =>
+    isQtiAssessmentTestResource(resource.type),
+  );
+  diagnosePrimaryResourceHrefs([...itemResources, ...assessmentTestResources], diagnostics);
+
+  const packageShape = detectPackageShape(itemResources, assessmentTestResources, diagnostics);
+  const assessmentTest = parseAssessmentTestPackageModel(
+    packageShape,
+    assessmentTestResources,
+    entriesByPath,
+    xmlFilesByPath,
+    diagnostics,
+  );
+  const itemReferences = itemReferencesForPackageShape(
+    packageShape,
+    itemResources,
+    assessmentTest,
+    diagnostics,
+  );
+  const items = parsePackageItems(itemReferences, entriesByPath, xmlFilesByPath, diagnostics);
+  const assets = collectPackageAssets(
+    resourcesByIdentifier,
+    assessmentTest,
+    items,
+    entriesByPath,
+    diagnostics,
+  );
+  const manifestStandards = manifestRoot
+    ? parseStandardAlignments(manifestRoot, QTI_PACKAGE_MANIFEST_PATH)
+    : [];
+  const standards = uniqueStandards([
+    ...manifestStandards,
+    ...(assessmentTest?.standards ?? []),
+    ...items.flatMap((item) => item.standards),
+  ]);
+  const timing = primaryTiming(assessmentTest, items);
+  const title = packageTitle(manifestRoot, assessmentTest, items);
+
+  return {
+    ok: diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+    title,
+    packageShape,
+    items,
+    assets,
+    manifestResources,
+    assessmentTest,
+    timing,
+    standards,
+    diagnostics,
+  };
+}
+
+function indexEntries(
+  entries: readonly QtiPackageEntry[],
+  diagnostics: QtiDiagnostic[],
+): Map<string, QtiPackageEntry> {
+  const entriesByPath = new Map<string, QtiPackageEntry>();
+  for (const entry of entries) {
+    if (entriesByPath.has(entry.path)) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.entry.duplicate",
+        "error",
+        `QTI package contains duplicate entry ${entry.path}.`,
+        entry.path,
+      );
+      continue;
+    }
+    entriesByPath.set(entry.path, entry);
+  }
+  return entriesByPath;
+}