@longsightgroup/qti3-core 0.10.3 → 0.10.5

package/src/qti-package-manifest.ts

@@ -3,8 +3,8 @@ import { normalizePackagePath, pushPackageDiagnostic } from "./qti-package-paths
 import { parseStandardAlignments } from "./qti-package-metadata.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";
+import { QTI_PACKAGE_MANIFEST_NAMESPACE } from "./qti-namespaces.js";
 
 export const QTI_PACKAGE_MANIFEST_PATH = "imsmanifest.xml";
 
@@ -20,11 +20,15 @@ export function isQtiAssessmentTestResource(type: string): boolean {
 
 export function parseManifestResources(
   manifestRoot: QtiPackageXmlNode,
-  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+  entriesByPath: { has(path: string): boolean },
   diagnostics: QtiDiagnostic[],
 ): QtiManifestResource[] {
-  const resourceNodes = packageDescendants(manifestRoot, "resources").flatMap((resources) =>
-    childPackageElements(resources, "resource"),
+  const resourceNodes = packageDescendants(
+    manifestRoot,
+    "resources",
+    QTI_PACKAGE_MANIFEST_NAMESPACE,
+  ).flatMap((resources) =>
+    childPackageElements(resources, "resource", QTI_PACKAGE_MANIFEST_NAMESPACE),
   );
   const resources: QtiManifestResource[] = [];
 
@@ -67,11 +71,11 @@ export function parseManifestResources(
 
 function parseManifestFiles(
   resourceNode: QtiPackageXmlNode,
-  entriesByPath: ReadonlyMap<string, QtiPackageEntry>,
+  entriesByPath: { has(path: string): boolean },
   diagnostics: QtiDiagnostic[],
 ): QtiManifestFile[] {
   const files: QtiManifestFile[] = [];
-  for (const fileNode of packageDescendants(resourceNode, "file")) {
+  for (const fileNode of packageDescendants(resourceNode, "file", QTI_PACKAGE_MANIFEST_NAMESPACE)) {
     const rawHref = fileNode.attributes.href;
     if (!rawHref) {
       pushPackageDiagnostic(
@@ -105,7 +109,11 @@ function parseManifestDependencies(
   diagnostics: QtiDiagnostic[],
 ): string[] {
   const dependencies: string[] = [];
-  for (const dependencyNode of packageDescendants(resourceNode, "dependency")) {
+  for (const dependencyNode of packageDescendants(
+    resourceNode,
+    "dependency",
+    QTI_PACKAGE_MANIFEST_NAMESPACE,
+  )) {
     const identifierref = dependencyNode.attributes.identifierref;
     if (!identifierref) {
       pushPackageDiagnostic(

package/src/qti-package-metadata.ts

@@ -11,6 +11,7 @@ import type {
   QtiTimingMetadata,
 } from "./qti-package-types.js";
 import type { QtiDiagnostic } from "./types.js";
+import { QTI_ASI_NAMESPACE, QTI_PACKAGE_MANIFEST_NAMESPACE } from "./qti-namespaces.js";
 
 /** Known QTI / IMS CP alignment element names plus attribute-driven manifest metadata. */
 const STANDARD_ALIGNMENT_ELEMENT_NAMES = new Set([
@@ -34,7 +35,7 @@ export function parseTimingMetadata(
   diagnostics: QtiDiagnostic[],
   parsedTimeLimits?: QtiTimeLimits,
 ): QtiTimingMetadata | undefined {
-  const timeLimitsNode = childPackageElements(root, "qti-time-limits")[0];
+  const timeLimitsNode = childPackageElements(root, "qti-time-limits", QTI_ASI_NAMESPACE)[0];
   const timeLimits = parsedTimeLimits ?? parseTimeLimits(timeLimitsNode, sourcePath, diagnostics);
   const timeDependent = parseXmlBoolean(root.attributes["time-dependent"]);
   if (!timeLimitsNode && timeDependent === undefined) return undefined;
@@ -281,22 +282,34 @@ function optionalFiniteNumber(raw: string | undefined): number | undefined {
   return Number.isFinite(value) ? value : undefined;
 }
 
-export function primaryTiming(
+export function primaryTimingFromScan(
   assessmentTest: QtiAssessmentTestPackageModel | undefined,
-  items: readonly QtiPackageItem[],
+  timedItemCount: number,
+  soleItemTiming: QtiTimingMetadata | undefined,
 ): QtiTimingMetadata | undefined {
   if (assessmentTest?.timing) return assessmentTest.timing;
+  return timedItemCount === 1 ? soleItemTiming : undefined;
+}
+
+export function primaryTiming(
+  assessmentTest: QtiAssessmentTestPackageModel | undefined,
+  items: readonly Pick<QtiPackageItem, "timing">[],
+): QtiTimingMetadata | undefined {
   const timedItems = items.filter((item) => item.timing !== undefined);
-  return timedItems.length === 1 ? timedItems[0]?.timing : undefined;
+  return primaryTimingFromScan(
+    assessmentTest,
+    timedItems.length,
+    timedItems.length === 1 ? timedItems[0]?.timing : undefined,
+  );
 }
 
 export function packageTitle(
   manifestRoot: QtiPackageXmlNode | undefined,
   assessmentTest: QtiAssessmentTestPackageModel | undefined,
-  items: readonly QtiPackageItem[],
+  items: readonly Pick<QtiPackageItem, "title">[],
 ): string {
   const manifestTitle = manifestRoot
-    ? packageDescendants(manifestRoot, "title")
+    ? packageDescendants(manifestRoot, "title", QTI_PACKAGE_MANIFEST_NAMESPACE)
         .map((node) => node.text.trim())
         .find((text) => text.length > 0)
     : undefined;

package/src/qti-package-plan.ts

@@ -0,0 +1,168 @@
+import type { QtiPackageXmlNode } from "./package-xml.js";
+import { collectPackageAssets } from "./qti-package-assets.js";
+import { QTI_PACKAGE_MANIFEST_PATH } from "./qti-package-manifest.js";
+import {
+  packageTitle,
+  parseStandardAlignments,
+  primaryTimingFromScan,
+  uniqueStandards,
+} from "./qti-package-metadata.js";
+import { pushPackageDiagnostic } from "./qti-package-paths.js";
+import {
+  detectPackageShape,
+  diagnoseManifestDependencyReferences,
+  diagnosePrimaryResourceHrefs,
+  indexManifestResources,
+  isQtiAssessmentTestResource,
+  isQtiItemResource,
+  parseManifestResources,
+} from "./qti-package-manifest.js";
+import { pushXmlDiagnostics, type PackageXmlFile } from "./qti-package-xml.js";
+import type {
+  QtiAssessmentTestPackageModel,
+  QtiManifestResource,
+  QtiPackageItem,
+  QtiPackageParseResult,
+  QtiPackageShape,
+  QtiStandardAlignment,
+  QtiTimingMetadata,
+} from "./qti-package-types.js";
+import { QTI_PACKAGE_MANIFEST_NAMESPACE } from "./qti-namespaces.js";
+import type { QtiDiagnostic } from "./types.js";
+
+/** Package metadata without extracted bodies or retained item models. */
+export type QtiPackageSummary = Omit<QtiPackageParseResult, "items" | "entries"> & {
+  readonly itemCount: number;
+};
+
+/** Inspect manifest semantics against an entry inventory without reading item bodies. */
+export function inspectPackageManifest(
+  entriesByPath: { has(path: string): boolean },
+  manifestXml: PackageXmlFile | undefined,
+  diagnostics: QtiDiagnostic[],
+) {
+  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.uri === QTI_PACKAGE_MANIFEST_NAMESPACE
+      ? manifestXml.root
+      : undefined;
+  if (manifestXml?.root && !manifestRoot) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.manifest.root",
+      "error",
+      manifestXml.root.localName === "manifest"
+        ? `Expected imsmanifest.xml manifest in namespace ${QTI_PACKAGE_MANIFEST_NAMESPACE}, found ${manifestXml.root.uri ?? "(none)"}.`
+        : `Expected imsmanifest.xml root manifest, found ${manifestXml.root.localName}.`,
+      QTI_PACKAGE_MANIFEST_PATH,
+    );
+  }
+
+  const manifestResources = manifestRoot
+    ? parseManifestResources(manifestRoot, entriesByPath, diagnostics)
+    : [];
+  const resourcesByIdentifier = indexManifestResources(manifestResources, diagnostics);
+  diagnoseManifestDependencyReferences(manifestResources, resourcesByIdentifier, diagnostics);
+
+  const itemResources = manifestResources.filter((resource) => isQtiItemResource(resource.type));
+  const assessmentTestResources = manifestResources.filter((resource) =>
+    isQtiAssessmentTestResource(resource.type),
+  );
+  diagnosePrimaryResourceHrefs([...itemResources, ...assessmentTestResources], diagnostics);
+
+  const packageShape = detectPackageShape(itemResources, assessmentTestResources, diagnostics);
+  return {
+    manifestRoot,
+    manifestResources,
+    resourcesByIdentifier,
+    itemResources,
+    assessmentTestResources,
+    packageShape,
+  };
+}
+
+export interface BuildPackageSummaryInput {
+  readonly manifestRoot: QtiPackageXmlNode | undefined;
+  readonly manifestResources: readonly QtiManifestResource[];
+  readonly resourcesByIdentifier: ReadonlyMap<string, QtiManifestResource>;
+  readonly packageShape: QtiPackageShape;
+  readonly assessmentTest: QtiAssessmentTestPackageModel | undefined;
+  readonly assetItems: readonly Pick<
+    QtiPackageItem,
+    "href" | "manifestResourceIdentifier" | "assetHrefs"
+  >[];
+  readonly titleItems: readonly Pick<QtiPackageItem, "title">[];
+  readonly timedItemCount: number;
+  readonly soleItemTiming: QtiTimingMetadata | undefined;
+  readonly itemStandards: readonly QtiStandardAlignment[];
+  readonly entriesByPath: { has(path: string): boolean };
+  readonly diagnostics: QtiDiagnostic[];
+  readonly itemCount: number;
+}
+
+/** Build canonical package metadata shared by sync and incremental parsers. */
+export function buildPackageSummary(input: BuildPackageSummaryInput): QtiPackageSummary {
+  const assets = collectPackageAssets(
+    input.resourcesByIdentifier,
+    input.assessmentTest,
+    input.assetItems,
+    input.entriesByPath,
+    input.diagnostics,
+  );
+  return {
+    ok: input.diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+    title: packageTitle(input.manifestRoot, input.assessmentTest, input.titleItems),
+    packageShape: input.packageShape,
+    manifestResources: input.manifestResources,
+    assessmentTest: input.assessmentTest,
+    assets,
+    standards: uniqueStandards([
+      ...(input.manifestRoot
+        ? parseStandardAlignments(input.manifestRoot, QTI_PACKAGE_MANIFEST_PATH)
+        : []),
+      ...(input.assessmentTest?.standards ?? []),
+      ...input.itemStandards,
+    ]),
+    timing: primaryTimingFromScan(input.assessmentTest, input.timedItemCount, input.soleItemTiming),
+    diagnostics: input.diagnostics,
+    itemCount: input.itemCount,
+  };
+}
+
+export function failedPackageSummary(diagnostics: QtiDiagnostic[]): QtiPackageSummary {
+  return {
+    ok: false,
+    title: "",
+    packageShape: "unknown",
+    manifestResources: [],
+    assessmentTest: undefined,
+    assets: [],
+    standards: [],
+    timing: undefined,
+    itemCount: 0,
+    diagnostics,
+  };
+}
+
+export function enforceDiagnosticLimit(diagnostics: QtiDiagnostic[], maxDiagnostics: number): void {
+  if (diagnostics.length < maxDiagnostics) return;
+  diagnostics.length = maxDiagnostics;
+  pushPackageDiagnostic(
+    diagnostics,
+    "package.diagnostics.limit",
+    "error",
+    "Package processing stopped at the diagnostic limit.",
+  );
+}

package/src/qti-package-stream.ts

@@ -0,0 +1,254 @@
+import {
+  itemReferencesForPackageShape,
+  parseAssessmentTestPackageModel,
+  parsePackageItem,
+} from "./qti-package-items.js";
+import { QTI_PACKAGE_MANIFEST_PATH } from "./qti-package-manifest.js";
+import {
+  buildPackageSummary,
+  enforceDiagnosticLimit,
+  failedPackageSummary,
+  inspectPackageManifest,
+  type QtiPackageSummary,
+} from "./qti-package-plan.js";
+import { normalizePackagePath, pushPackageDiagnostic } from "./qti-package-paths.js";
+import type { QtiPackageItem } from "./qti-package-types.js";
+import { parsePackageXml } from "./qti-package-xml.js";
+import type { QtiPackageEntry } from "./qti-package-zip.js";
+import type { QtiDiagnostic } from "./types.js";
+
+/** An immutable entry inventory and host-owned, bounded reads of decoded entry bytes. */
+export interface QtiPackageSource {
+  readonly entries: readonly { readonly path: string; readonly size: number }[];
+  /** Enforce maxBytes during extraction, before allocating an oversized body. */
+  readonly readEntry: (path: string, maxBytes: number) => Promise<Uint8Array>;
+}
+
+/** Explicit resource budgets for an incremental package read. */
+export interface QtiPackageStreamLimits {
+  readonly maxEntries: number;
+  readonly maxEntryBytes: number;
+  readonly maxTotalBytes: number;
+  readonly maxDiagnostics: number;
+}
+
+/** Package metadata without extracted bodies or retained item models. */
+export type QtiPackageStreamSummary = QtiPackageSummary;
+
+/** Items are provisional until the terminal summary reports ok; hosts must stage them. */
+export type QtiPackageStreamEvent =
+  | { readonly kind: "item"; readonly index: number; readonly item: QtiPackageItem }
+  | { readonly kind: "summary"; readonly summary: QtiPackageStreamSummary };
+
+/**
+ * Parse immutable package entries sequentially with canonical package semantics.
+ *
+ * The caller owns ZIP/object storage and must not collect item events when bounded
+ * memory is required. Assets are described in the terminal summary, never loaded.
+ * Breaking iteration stops subsequent reads. Read failures become safe diagnostics.
+ */
+export async function* parseQtiPackageStream(
+  source: QtiPackageSource,
+  limits: QtiPackageStreamLimits,
+): AsyncGenerator<QtiPackageStreamEvent> {
+  const diagnostics: QtiDiagnostic[] = [];
+  const inventory = inspectInventory(source, limits, diagnostics);
+  if (!inventory) {
+    yield { kind: "summary", summary: failedPackageSummary(diagnostics) };
+    return;
+  }
+  const read = createEntryReader(source, inventory, limits, diagnostics);
+  const manifestEntry = await read(QTI_PACKAGE_MANIFEST_PATH);
+  const manifest = inspectPackageManifest(
+    inventory,
+    manifestEntry ? parsePackageXml(manifestEntry) : undefined,
+    diagnostics,
+  );
+  // Only the primary assessment test supplies the package structure. The shared
+  // parser diagnoses additional test resources without loading their bodies.
+  const testEntries = new Map<string, QtiPackageEntry>();
+  const testHref = manifest.assessmentTestResources[0]?.href;
+  if (testHref !== undefined) {
+    const entry = await read(testHref);
+    if (entry) testEntries.set(testHref, entry);
+  }
+  const assessmentTest = parseAssessmentTestPackageModel(
+    manifest.packageShape,
+    manifest.assessmentTestResources,
+    testEntries,
+    new Map(),
+    diagnostics,
+  );
+  const references = itemReferencesForPackageShape(
+    manifest.packageShape,
+    manifest.itemResources,
+    assessmentTest,
+    diagnostics,
+  );
+  const assetItems: Pick<QtiPackageItem, "href" | "manifestResourceIdentifier" | "assetHrefs">[] =
+    [];
+  const itemStandards: QtiPackageItem["standards"][number][] = [];
+  const titleItems: Pick<QtiPackageItem, "title">[] = [];
+  const seen = new Set<string>();
+  let itemCount = 0;
+  let timedItemCount = 0;
+  let soleItemTiming: QtiPackageItem["timing"] | undefined;
+  for (const reference of references) {
+    if (diagnostics.length >= limits.maxDiagnostics) break;
+    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 = await read(reference.href);
+    if (!entry) continue;
+    const item = parsePackageItem(reference, entry, undefined, diagnostics);
+    if (item.title !== undefined && titleItems.length === 0) {
+      titleItems.push({ title: item.title });
+    }
+    if (item.timing !== undefined) {
+      timedItemCount += 1;
+      soleItemTiming = item.timing;
+    }
+    itemStandards.push(...item.standards);
+    assetItems.push({
+      href: item.href,
+      manifestResourceIdentifier: item.manifestResourceIdentifier,
+      assetHrefs: item.assetHrefs,
+    });
+    yield { kind: "item", index: itemCount++, item };
+  }
+  enforceDiagnosticLimit(diagnostics, limits.maxDiagnostics);
+  yield {
+    kind: "summary",
+    summary: buildPackageSummary({
+      manifestRoot: manifest.manifestRoot,
+      manifestResources: manifest.manifestResources,
+      resourcesByIdentifier: manifest.resourcesByIdentifier,
+      packageShape: manifest.packageShape,
+      assessmentTest,
+      assetItems,
+      titleItems,
+      timedItemCount,
+      soleItemTiming,
+      itemStandards,
+      entriesByPath: inventory,
+      diagnostics,
+      itemCount,
+    }),
+  };
+}
+
+function createEntryReader(
+  source: QtiPackageSource,
+  inventory: ReadonlyMap<string, number>,
+  limits: QtiPackageStreamLimits,
+  diagnostics: QtiDiagnostic[],
+): (path: string) => Promise<QtiPackageEntry | undefined> {
+  return async (path) => {
+    const size = inventory.get(path);
+    if (size === undefined) return undefined;
+    try {
+      const bytes = await source.readEntry(path, limits.maxEntryBytes);
+      if (!(bytes instanceof Uint8Array) || bytes.byteLength !== size) {
+        pushPackageDiagnostic(
+          diagnostics,
+          "package.entry.size",
+          "error",
+          "Package entry size does not match its immutable inventory.",
+          path,
+        );
+        return undefined;
+      }
+      return { path, bytes };
+    } catch {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.entry.read",
+        "error",
+        "Package entry could not be read.",
+        path,
+      );
+      return undefined;
+    }
+  };
+}
+
+function inspectInventory(
+  source: QtiPackageSource,
+  limits: QtiPackageStreamLimits,
+  diagnostics: QtiDiagnostic[],
+): Map<string, number> | undefined {
+  if (!validStreamLimits(limits)) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.limits.invalid",
+      "error",
+      "Package limits must be positive safe integers.",
+    );
+    return undefined;
+  }
+  if (source.entries.length > limits.maxEntries) {
+    pushPackageDiagnostic(
+      diagnostics,
+      "package.entries.limit",
+      "error",
+      "Package contains more entries than allowed.",
+    );
+    return undefined;
+  }
+  const inventory = new Map<string, number>();
+  let total = 0;
+  for (const entry of source.entries) {
+    const path = normalizePackagePath(entry.path, "entry", diagnostics);
+    if (!path) return undefined;
+    if (path !== entry.path || inventory.has(path)) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.entry.duplicate",
+        "error",
+        "Package inventory paths must be unique and canonical.",
+        entry.path,
+      );
+      return undefined;
+    }
+    total += entry.size;
+    if (
+      !Number.isSafeInteger(entry.size) ||
+      entry.size < 0 ||
+      entry.size > limits.maxEntryBytes ||
+      !Number.isSafeInteger(total) ||
+      total > limits.maxTotalBytes
+    ) {
+      pushPackageDiagnostic(
+        diagnostics,
+        "package.bytes.limit",
+        "error",
+        "Package entry or total size exceeds its configured budget.",
+        path,
+      );
+      return undefined;
+    }
+    inventory.set(path, entry.size);
+  }
+  return inventory;
+}
+
+function validStreamLimits(limits: QtiPackageStreamLimits): boolean {
+  return (
+    Number.isSafeInteger(limits.maxEntries) &&
+    limits.maxEntries > 0 &&
+    Number.isSafeInteger(limits.maxEntryBytes) &&
+    limits.maxEntryBytes > 0 &&
+    Number.isSafeInteger(limits.maxTotalBytes) &&
+    limits.maxTotalBytes > 0 &&
+    Number.isSafeInteger(limits.maxDiagnostics) &&
+    limits.maxDiagnostics > 0
+  );
+}

package/src/qti-package-xml.ts

@@ -39,22 +39,35 @@ export function pushXmlDiagnostics(xmlFile: PackageXmlFile, diagnostics: QtiDiag
   }
 }
 
+/** Return direct package-XML children, optionally restricted by local name and namespace. */
 export function childPackageElements(
   node: QtiPackageXmlNode,
   localName?: string,
+  namespaceUri?: string,
 ): QtiPackageXmlNode[] {
-  return node.children.filter((child) => !localName || child.localName === localName);
+  return node.children.filter(
+    (child) =>
+      (!localName || child.localName === localName) &&
+      (namespaceUri === undefined || child.uri === namespaceUri),
+  );
 }
 
+/** Return package-XML descendants, optionally restricted by local name and namespace. */
 export function packageDescendants(
   node: QtiPackageXmlNode | undefined,
   localName?: string,
+  namespaceUri?: 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));
+    if (
+      (!localName || child.localName === localName) &&
+      (namespaceUri === undefined || child.uri === namespaceUri)
+    ) {
+      found.push(child);
+    }
+    found.push(...packageDescendants(child, localName, namespaceUri));
   }
   return found;
 }