@longsightgroup/qti3-core 0.9.3 → 0.9.5

package/src/qti-package-items.ts

@@ -0,0 +1,240 @@
+import type { QtiPackageXmlNode } from "./package-xml.js";
+import { parseQtiXml } from "./parser.js";
+import { pushPackageDiagnostic } from "./qti-package-paths.js";
+import { discoverContentAssetHrefs } from "./qti-package-assets.js";
+import { QTI_PACKAGE_MANIFEST_PATH } from "./qti-package-manifest.js";
+import { parseStandardAlignments, parseTimingMetadata } from "./qti-package-metadata.js";
+import type {
+  QtiAssessmentTestItemRef,
+  QtiAssessmentTestPackageModel,
+  QtiManifestResource,
+  QtiPackageItem,
+  QtiPackageItemSource,
+  QtiPackageShape,
+} from "./qti-package-types.js";
+import {
+  packageDescendants,
+  parsePackageXml,
+  pushXmlDiagnostics,
+  resolvePackageHref,
+  scopeDiagnosticToPackagePath,
+  type PackageXmlFile,
+} from "./qti-package-xml.js";
+import type { QtiPackageEntry } from "./qti-package-zip.js";
+import type { QtiDiagnostic } from "./types.js";
+
+export interface PackageItemReference {
+  readonly href: string;
+  readonly source: QtiPackageItemSource;
+  readonly manifestResourceIdentifier?: string | undefined;
+  readonly assessmentItemRefIdentifier?: string | undefined;
+}
+
+export function parseAssessmentTestPackageModel(
+  packageShape: QtiPackageShape,
+  assessmentTestResources: readonly QtiManifestResource[],
+  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+  xmlFilesByPath: ReadonlyMap<string, PackageXmlFile>,
+  diagnostics: QtiDiagnostic[],
+): QtiAssessmentTestPackageModel | undefined {
+  if (packageShape !== "assessment-test-resource") return undefined;
+
+  const firstResource = assessmentTestResources[0];
+  if (!firstResource) return undefined;
+
+  if (assessmentTestResources.length > 1) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.assessmentTest.resource.ambiguous",
+      "error",
+      "Manifest contains multiple QTI assessment-test resources.",
+      QTI_PACKAGE_MANIFEST_PATH,
+    );
+  }
+
+  const href = firstResource.href;
+  if (!href) return undefined;
+  if (!entriesByPath.has(href)) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.assessmentTest.missing",
+      "error",
+      `Assessment test resource ${href} was not found in the package.`,
+      href,
+    );
+    return undefined;
+  }
+
+  const entry = entriesByPath.get(href);
+  if (!entry) return undefined;
+  const xmlFile = xmlFilesByPath.get(href) ?? parsePackageXml(entry);
+  const testDiagnostics: QtiDiagnostic[] = [];
+  pushXmlDiagnostics(xmlFile, testDiagnostics);
+  const root = xmlFile.root?.localName === "qti-assessment-test" ? xmlFile.root : undefined;
+  if (xmlFile.root && !root) {
+    pushPackageDiagnostic(
+      testDiagnostics,
+      "package.assessmentTest.root",
+      "error",
+      `Expected qti-assessment-test root, found ${xmlFile.root.localName}.`,
+      href,
+    );
+  }
+
+  const itemRefs = root ? parseAssessmentTestItemRefs(root, href, testDiagnostics) : [];
+  const assetHrefs = root ? discoverContentAssetHrefs(xmlFile, testDiagnostics) : [];
+  const scopedDiagnostics = testDiagnostics.map((diagnostic) =>
+    scopeDiagnosticToPackagePath(href, diagnostic),
+  );
+  diagnostics.push(...scopedDiagnostics);
+
+  return {
+    href,
+    identifier: root?.attributes.identifier ?? "",
+    title: root?.attributes.title,
+    manifestResourceIdentifier: firstResource.identifier,
+    itemRefs,
+    timing: root ? parseTimingMetadata(root, href) : undefined,
+    standards: root ? parseStandardAlignments(root, href) : [],
+    assetHrefs,
+    diagnostics: scopedDiagnostics,
+    attributes: root ? { ...root.attributes } : {},
+    xml: xmlFile.xml,
+  };
+}
+
+function parseAssessmentTestItemRefs(
+  root: QtiPackageXmlNode,
+  sourcePath: string,
+  diagnostics: QtiDiagnostic[],
+): QtiAssessmentTestItemRef[] {
+  const itemRefs: QtiAssessmentTestItemRef[] = [];
+  for (const refNode of packageDescendants(root, "qti-assessment-item-ref")) {
+    const rawHref = refNode.attributes.href;
+    if (!rawHref) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.assessmentTest.itemRef.href.missing",
+        "error",
+        "qti-assessment-item-ref is missing href.",
+        sourcePath,
+      );
+      continue;
+    }
+
+    const href = resolvePackageHref(sourcePath, rawHref, diagnostics);
+    if (!href) continue;
+    itemRefs.push({
+      identifier: refNode.attributes.identifier,
+      href,
+      attributes: { ...refNode.attributes },
+    });
+  }
+  return itemRefs;
+}
+
+export function itemReferencesForPackageShape(
+  packageShape: QtiPackageShape,
+  itemResources: readonly QtiManifestResource[],
+  assessmentTest: QtiAssessmentTestPackageModel | undefined,
+  diagnostics: QtiDiagnostic[],
+): PackageItemReference[] {
+  if (packageShape === "assessment-test-resource") {
+    return (assessmentTest?.itemRefs ?? []).map((itemRef) => ({
+      href: itemRef.href,
+      source: "assessment-test",
+      assessmentItemRefIdentifier: itemRef.identifier,
+    }));
+  }
+
+  if (packageShape !== "manifest-item-resources") return [];
+
+  const references: PackageItemReference[] = [];
+  const seen = new Set<string>();
+  for (const resource of itemResources) {
+    const href = resource.href;
+    if (!href) continue;
+    if (seen.has(href)) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.itemResource.href.duplicate",
+        "error",
+        `Multiple manifest item resources point to ${href}.`,
+        href,
+      );
+      continue;
+    }
+    seen.add(href);
+    references.push({
+      href,
+      source: "manifest",
+      manifestResourceIdentifier: resource.identifier,
+    });
+  }
+  return references;
+}
+
+export function parsePackageItems(
+  references: readonly PackageItemReference[],
+  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+  xmlFilesByPath: ReadonlyMap<string, PackageXmlFile>,
+  diagnostics: QtiDiagnostic[],
+): QtiPackageItem[] {
+  const items: QtiPackageItem[] = [];
+  const seen = new Set<string>();
+
+  for (const reference of references) {
+    if (seen.has(reference.href)) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.item.reference.duplicate",
+        "warning",
+        `Package item ${reference.href} is referenced more than once.`,
+        reference.href,
+      );
+      continue;
+    }
+    seen.add(reference.href);
+
+    const entry = entriesByPath.get(reference.href);
+    if (!entry) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.item.missing",
+        "error",
+        `Package item reference ${reference.href} was not found.`,
+        reference.href,
+      );
+      continue;
+    }
+
+    const xmlFile = xmlFilesByPath.get(reference.href) ?? parsePackageXml(entry);
+    // Full QTI parse for document model; lightweight tree above supplies metadata and asset refs.
+    const parsed = parseQtiXml(xmlFile.xml);
+    const itemDiagnostics = parsed.diagnostics.map((diagnostic) =>
+      scopeDiagnosticToPackagePath(reference.href, diagnostic),
+    );
+    diagnostics.push(...itemDiagnostics);
+
+    const assetHrefs = xmlFile.root ? discoverContentAssetHrefs(xmlFile, diagnostics) : [];
+    const root = xmlFile.root?.localName === "qti-assessment-item" ? xmlFile.root : undefined;
+    const item = parsed.document?.item;
+
+    items.push({
+      href: reference.href,
+      source: reference.source,
+      manifestResourceIdentifier: reference.manifestResourceIdentifier,
+      assessmentItemRefIdentifier: reference.assessmentItemRefIdentifier,
+      identifier: item?.identifier,
+      title: item?.title,
+      document: parsed.document,
+      timing: root ? parseTimingMetadata(root, reference.href) : undefined,
+      standards: root ? parseStandardAlignments(root, reference.href) : [],
+      assetHrefs,
+      diagnostics: itemDiagnostics,
+      xml: xmlFile.xml,
+    });
+  }
+
+  return items;
+}

package/src/qti-package-manifest.ts

@@ -0,0 +1,210 @@
+import type { QtiPackageXmlNode } from "./package-xml.js";
+import { normalizePackagePath, pushPackageDiagnostic } from "./qti-package-paths.js";
+import type { QtiManifestFile, QtiManifestResource, QtiPackageShape } from "./qti-package-types.js";
+import { childPackageElements, packageDescendants, stripHrefSuffix } from "./qti-package-xml.js";
+import type { QtiPackageEntry } from "./qti-package-zip.js";
+import type { QtiDiagnostic } from "./types.js";
+
+export const QTI_PACKAGE_MANIFEST_PATH = "imsmanifest.xml";
+
+export function isQtiItemResource(type: string): boolean {
+  return type.toLowerCase().startsWith("imsqti_item_xmlv3p0");
+}
+
+export function isQtiAssessmentTestResource(type: string): boolean {
+  return type.toLowerCase().startsWith("imsqti_test_xmlv3p0");
+}
+
+export function parseManifestResources(
+  manifestRoot: QtiPackageXmlNode,
+  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+  diagnostics: QtiDiagnostic[],
+): QtiManifestResource[] {
+  const resourceNodes = packageDescendants(manifestRoot, "resources").flatMap((resources) =>
+    childPackageElements(resources, "resource"),
+  );
+  const resources: QtiManifestResource[] = [];
+
+  for (const node of resourceNodes) {
+    const identifier = node.attributes.identifier ?? "";
+    if (identifier.length === 0) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.resource.identifier.missing",
+        "error",
+        "Manifest resource is missing an identifier.",
+        QTI_PACKAGE_MANIFEST_PATH,
+      );
+    }
+
+    const files = parseManifestFiles(node, entriesByPath, diagnostics);
+    const href =
+      node.attributes.href === undefined
+        ? firstXmlManifestFileHref(files)
+        : normalizePackagePath(
+            stripHrefSuffix(node.attributes.href),
+            `manifest resource ${identifier || "(missing identifier)"} href`,
+            diagnostics,
+          );
+    const dependencies = parseManifestDependencies(node, diagnostics);
+
+    resources.push({
+      identifier,
+      type: node.attributes.type ?? "",
+      href,
+      files,
+      dependencies,
+      attributes: { ...node.attributes },
+    });
+  }
+
+  return resources;
+}
+
+function parseManifestFiles(
+  resourceNode: QtiPackageXmlNode,
+  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+  diagnostics: QtiDiagnostic[],
+): QtiManifestFile[] {
+  const files: QtiManifestFile[] = [];
+  for (const fileNode of packageDescendants(resourceNode, "file")) {
+    const rawHref = fileNode.attributes.href;
+    if (!rawHref) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.file.href.missing",
+        "error",
+        "Manifest file entry is missing href.",
+        QTI_PACKAGE_MANIFEST_PATH,
+      );
+      continue;
+    }
+
+    const href = normalizePackagePath(stripHrefSuffix(rawHref), "manifest file href", diagnostics);
+    if (!href) continue;
+    files.push({ href, attributes: { ...fileNode.attributes } });
+    if (!entriesByPath.has(href)) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.file.missing",
+        "error",
+        `Manifest file reference ${href} was not found in the package.`,
+        href,
+      );
+    }
+  }
+  return files;
+}
+
+function parseManifestDependencies(
+  resourceNode: QtiPackageXmlNode,
+  diagnostics: QtiDiagnostic[],
+): string[] {
+  const dependencies: string[] = [];
+  for (const dependencyNode of packageDescendants(resourceNode, "dependency")) {
+    const identifierref = dependencyNode.attributes.identifierref;
+    if (!identifierref) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.dependency.identifierref.missing",
+        "error",
+        "Manifest dependency is missing identifierref.",
+        QTI_PACKAGE_MANIFEST_PATH,
+      );
+      continue;
+    }
+    dependencies.push(identifierref);
+  }
+  return [...new Set(dependencies)];
+}
+
+function firstXmlManifestFileHref(files: readonly QtiManifestFile[]): string | undefined {
+  return files.find((file) => file.href.toLowerCase().endsWith(".xml"))?.href;
+}
+
+export function indexManifestResources(
+  resources: readonly QtiManifestResource[],
+  diagnostics: QtiDiagnostic[],
+): Map<string, QtiManifestResource> {
+  const byIdentifier = new Map<string, QtiManifestResource>();
+  for (const resource of resources) {
+    const identifier = resource.identifier;
+    if (identifier.length === 0) continue;
+    if (byIdentifier.has(identifier)) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.resource.identifier.duplicate",
+        "error",
+        `Manifest contains duplicate resource identifier ${identifier}.`,
+        QTI_PACKAGE_MANIFEST_PATH,
+      );
+      continue;
+    }
+    byIdentifier.set(identifier, resource);
+  }
+  return byIdentifier;
+}
+
+export function diagnoseManifestDependencyReferences(
+  resources: readonly QtiManifestResource[],
+  resourcesByIdentifier: ReadonlyMap<string, QtiManifestResource>,
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const resource of resources) {
+    for (const dependency of resource.dependencies) {
+      if (resourcesByIdentifier.has(dependency)) continue;
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.manifest.dependency.missing",
+        "error",
+        `Manifest resource ${resource.identifier} depends on missing resource ${dependency}.`,
+        QTI_PACKAGE_MANIFEST_PATH,
+      );
+    }
+  }
+}
+
+export function diagnosePrimaryResourceHrefs(
+  resources: readonly QtiManifestResource[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const resource of resources) {
+    if (resource.href) continue;
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.manifest.resource.href.missing",
+      "error",
+      `Manifest resource ${resource.identifier || "(missing identifier)"} is missing a primary XML href.`,
+      QTI_PACKAGE_MANIFEST_PATH,
+    );
+  }
+}
+
+export function detectPackageShape(
+  itemResources: readonly QtiManifestResource[],
+  assessmentTestResources: readonly QtiManifestResource[],
+  diagnostics: QtiDiagnostic[],
+): QtiPackageShape {
+  if (assessmentTestResources.length > 0 && itemResources.length > 0) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.shape.ambiguous",
+      "error",
+      "Manifest contains both QTI item resources and QTI assessment-test resources.",
+      QTI_PACKAGE_MANIFEST_PATH,
+    );
+    return "unknown";
+  }
+
+  if (assessmentTestResources.length > 0) return "assessment-test-resource";
+  if (itemResources.length > 0) return "manifest-item-resources";
+
+  pushPackageDiagnostic(
+    diagnostics,
+    "package.shape.unsupported",
+    "error",
+    "Manifest does not contain QTI item or assessment-test resources.",
+    QTI_PACKAGE_MANIFEST_PATH,
+  );
+  return "unknown";
+}

package/src/qti-package-metadata.ts

@@ -0,0 +1,143 @@
+import type { QtiPackageXmlNode } from "./package-xml.js";
+import { parseXmlBoolean } from "./parser-values.js";
+import { packageDescendants } from "./qti-package-xml.js";
+import type {
+  QtiAssessmentTestPackageModel,
+  QtiPackageItem,
+  QtiStandardAlignment,
+  QtiTimingMetadata,
+} from "./qti-package-types.js";
+
+/** Known QTI / IMS CP alignment element names plus attribute-driven manifest metadata. */
+const STANDARD_ALIGNMENT_ELEMENT_NAMES = new Set([
+  "standard-alignment",
+  "qti-standard-alignment",
+  "alignment-objective",
+]);
+
+const STANDARD_ALIGNMENT_ATTRIBUTE_NAMES = new Set([
+  "standard-id",
+  "standardIdentifier",
+  "standard-framework",
+  "standardFramework",
+  "target-id",
+  "targetIdentifier",
+]);
+
+export function parseTimingMetadata(
+  root: QtiPackageXmlNode,
+  sourcePath: string,
+): QtiTimingMetadata | undefined {
+  const timeLimits = packageDescendants(root, "qti-time-limits")[0];
+  const timeDependent = parseXmlBoolean(root.attributes["time-dependent"]);
+  if (!timeLimits && timeDependent === undefined) return undefined;
+
+  return {
+    sourcePath,
+    timeDependent,
+    minTime: timeLimits?.attributes["min-time"],
+    maxTime: timeLimits?.attributes["max-time"],
+    allowLateSubmission: parseXmlBoolean(timeLimits?.attributes["allow-late-submission"]),
+    attributes: timeLimits ? { ...timeLimits.attributes } : {},
+  };
+}
+
+export function parseStandardAlignments(
+  root: QtiPackageXmlNode,
+  sourcePath: string,
+): QtiStandardAlignment[] {
+  const alignments: QtiStandardAlignment[] = [];
+  for (const node of packageDescendants(root)) {
+    if (!isStandardAlignmentNode(node)) continue;
+    const text = node.text.trim();
+    alignments.push({
+      sourcePath,
+      qtiName: node.localName,
+      identifier: firstAttribute(node, [
+        "identifier",
+        "id",
+        "standard-id",
+        "standardIdentifier",
+        "target-id",
+        "targetIdentifier",
+      ]),
+      framework: firstAttribute(node, [
+        "framework",
+        "standard-framework",
+        "standardFramework",
+        "educational-framework",
+        "educationalFramework",
+      ]),
+      targetName:
+        firstAttribute(node, ["target-name", "targetName", "name"]) ??
+        (text.length > 0 ? text : undefined),
+      targetUrl: firstAttribute(node, ["href", "url", "uri", "target-url", "targetUrl"]),
+      text: text.length > 0 ? text : undefined,
+      attributes: { ...node.attributes },
+    });
+  }
+  return alignments;
+}
+
+function isStandardAlignmentNode(node: QtiPackageXmlNode): boolean {
+  if (STANDARD_ALIGNMENT_ELEMENT_NAMES.has(node.localName)) return true;
+  return Object.keys(node.attributes).some((name) => STANDARD_ALIGNMENT_ATTRIBUTE_NAMES.has(name));
+}
+
+function firstAttribute(node: QtiPackageXmlNode, names: readonly string[]): string | undefined {
+  for (const name of names) {
+    const value = node.attributes[name];
+    if (value && value.trim().length > 0) return value.trim();
+  }
+  return undefined;
+}
+
+export function uniqueStandards(
+  standards: readonly QtiStandardAlignment[],
+): QtiStandardAlignment[] {
+  const seen = new Set<string>();
+  const unique: QtiStandardAlignment[] = [];
+  for (const standard of standards) {
+    const key = [
+      standard.sourcePath,
+      standard.qtiName,
+      standard.identifier ?? "",
+      standard.framework ?? "",
+      standard.targetName ?? "",
+      standard.targetUrl ?? "",
+      standard.text ?? "",
+    ].join("\u0000");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(standard);
+  }
+  return unique;
+}
+
+export function primaryTiming(
+  assessmentTest: QtiAssessmentTestPackageModel | undefined,
+  items: readonly QtiPackageItem[],
+): QtiTimingMetadata | undefined {
+  if (assessmentTest?.timing) return assessmentTest.timing;
+  const timedItems = items.filter((item) => item.timing !== undefined);
+  return timedItems.length === 1 ? timedItems[0]?.timing : undefined;
+}
+
+export function packageTitle(
+  manifestRoot: QtiPackageXmlNode | undefined,
+  assessmentTest: QtiAssessmentTestPackageModel | undefined,
+  items: readonly QtiPackageItem[],
+): string {
+  const manifestTitle = manifestRoot
+    ? packageDescendants(manifestRoot, "title")
+        .map((node) => node.text.trim())
+        .find((text) => text.length > 0)
+    : undefined;
+  return (
+    assessmentTest?.title ??
+    manifestTitle ??
+    items.find((item) => item.title !== undefined)?.title ??
+    manifestRoot?.attributes.identifier ??
+    ""
+  );
+}

package/src/qti-package-paths.ts

@@ -0,0 +1,56 @@
+import type { QtiDiagnostic } from "./types.js";
+
+/** Add a package parser diagnostic to an existing diagnostics list. */
+export function pushPackageDiagnostic(
+  diagnostics: QtiDiagnostic[],
+  code: string,
+  severity: QtiDiagnostic["severity"],
+  message: string,
+  path?: string,
+): void {
+  diagnostics.push({
+    code,
+    severity,
+    message,
+    path,
+  });
+}
+
+/** Normalize a package-relative path and diagnose absolute or escaping paths. */
+export function normalizePackagePath(
+  path: string,
+  context: string,
+  diagnostics: QtiDiagnostic[],
+): string | undefined {
+  if (path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path) || /^[a-z][a-z0-9+.-]*:/i.test(path)) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.path.absolute",
+      "error",
+      `${context} ${path} must be a package-relative path.`,
+      path,
+    );
+    return undefined;
+  }
+
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (parts.length === 0) {
+        pushPackageDiagnostic(
+          diagnostics,
+          "package.path.escape",
+          "error",
+          `${context} ${path} escapes the package root.`,
+          path,
+        );
+        return undefined;
+      }
+      parts.pop();
+      continue;
+    }
+    parts.push(part);
+  }
+  return parts.join("/");
+}