@longsightgroup/qti3-core 0.9.2 → 0.9.4

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("/");
+}

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,
+  };
+}