@longsightgroup/qti3-migrator 0.9.7 → 0.9.8

package/src/index.ts

@@ -1,42 +1,30 @@
-import {
-  detectPackageMediaType,
-  parseQtiXml,
-  validateAssessmentItem,
-  type QtiDiagnostic,
-} from "@longsightgroup/qti3-core";
-import {
-  qti3TrustedXmlFragment,
-  writeQti3AssessmentItemResult,
-  type Qti3AuthoringItem,
-} from "@longsightgroup/qti3-writer";
-import { diagnostic, hasErrors } from "./diagnostics.js";
+import { diagnostic } from "./diagnostics.js";
 import { migrationPathIdentifier } from "./identifiers.js";
+import { finalizeItemResult, finalizeItemResults } from "./item-finalize.js";
+import { migrateItemXml } from "./migrate-items.js";
+import { migrationPackageAssets } from "./assets.js";
 import { resolveOptions } from "./options.js";
 import { migrationResultToPackage } from "./package-result.js";
-import { migrateQti12Xml } from "./qti12-item.js";
-import { itemTitleFromXml, migrateQti2ItemXml } from "./qti2-item.js";
+import { migrateQtiResourceToQti3 } from "./resource-migration.js";
 import {
   detectMigrationSource,
   detectQtiMigrationSource,
   parseLegacyManifest,
   readMigrationSource,
-  type MigrationEntry,
   type MigrationSource,
 } from "./source.js";
 import type {
-  QtiMigrationAsset,
   QtiMigrationDetectionResult,
   QtiMigrationDiagnostic,
   QtiMigrationItemResult,
   QtiMigrationOptions,
-  QtiPackageMigrationResult,
   QtiMigrationPart,
   QtiMigrationResult,
-  QtiMigrationSourceFormat,
   QtiMigrationSourceInput,
+  QtiPackageMigrationResult,
 } from "./types.js";
 
-export { detectQtiMigrationSource };
+export { detectQtiMigrationSource, migrateQtiResourceToQti3 };
 export type {
   QtiMigrationAsset,
   QtiMigrationDetectionResult,
@@ -46,11 +34,15 @@ export type {
   QtiMigrationOptions,
   QtiPackageMigrationResult,
   QtiMigrationPart,
+  QtiMigrationResourceEntry,
+  QtiMigrationResourceInput,
   QtiMigrationRepairPolicy,
   QtiMigrationResult,
   QtiMigrationSourceFormat,
   QtiMigrationSourceInput,
   QtiMigrationUnsupportedPolicy,
+  QtiResourceMigrationResult,
+  QtiResourceMigrationStatus,
 } from "./types.js";
 
 export async function migrateQtiToQti3(
@@ -219,10 +211,13 @@ function migratePackageSource(
       });
       continue;
     }
-    const migratedItems = migrateItemXml(entry.text, href, sourceFormat, options);
+    const migratedItems = finalizeItemResults(
+      migrateItemXml(entry.text, href, sourceFormat, options),
+      href,
+      options,
+    );
     for (const item of migratedItems) {
-      const finalized = finalizeItemResult(item, href, options);
-      items.push({ ...finalized, assetHrefs: assetHrefsByItemHref.get(href) ?? [] });
+      items.push({ ...item, assetHrefs: assetHrefsByItemHref.get(href) ?? [] });
     }
   }
   return {
@@ -230,7 +225,7 @@ function migratePackageSource(
     sourceFormat,
     parts: [partFromItems("PART_1", manifest.title, items)],
     items,
-    assets: packageAssets(source.entries),
+    assets: migrationPackageAssets(source.entries),
     diagnostics,
   };
 }
@@ -242,12 +237,12 @@ function migrateItemSource(
 ): QtiMigrationResult {
   const sourceFormat = detection.sourceFormat!;
   const xml = source.xml ?? "";
-  const migratedItems = migrateItemXml(
-    xml,
-    source.filename ?? "item.xml",
-    sourceFormat,
+  const href = source.filename ?? "item.xml";
+  const migratedItems = finalizeItemResults(
+    migrateItemXml(xml, href, sourceFormat, options),
+    href,
     options,
-  ).map((item) => finalizeItemResult(item, source.filename ?? `${item.identifier}.xml`, options));
+  );
   return {
     title: migratedItems[0]?.title ?? source.filename ?? "Imported QTI Item",
     sourceFormat,
@@ -258,142 +253,6 @@ function migrateItemSource(
   };
 }
 
-function migrateItemXml(
-  xml: string,
-  path: string,
-  sourceFormat: QtiMigrationSourceFormat,
-  options: ReturnType<typeof resolveOptions>,
-): readonly PendingMigrationItem[] {
-  if (sourceFormat === "qti12") {
-    return migrateQti12Xml(xml, path, options).map((result, index) => ({
-      identifier: result.authoringItem?.identifier ?? `ITEM_${index + 1}`,
-      title: result.authoringItem?.title ?? itemTitleFromXmlSafe(xml),
-      authoringItem: result.authoringItem,
-      diagnostics: result.diagnostics,
-    }));
-  }
-  const result = migrateQti2ItemXml(xml, path, sourceFormat, options);
-  return [
-    {
-      identifier: result.authoringItem?.identifier ?? migrationPathIdentifier(path),
-      title: result.authoringItem?.title ?? itemTitleFromXmlSafe(xml),
-      authoringItem: result.authoringItem,
-      diagnostics: result.diagnostics,
-    },
-  ];
-}
-
-interface PendingMigrationItem {
-  readonly identifier: string;
-  readonly title: string;
-  readonly authoringItem?: Qti3AuthoringItem | undefined;
-  readonly diagnostics: readonly QtiMigrationDiagnostic[];
-}
-
-function finalizeItemResult(
-  pending: PendingMigrationItem,
-  href: string,
-  options: ReturnType<typeof resolveOptions>,
-): QtiMigrationItemResult {
-  const diagnostics = [...pending.diagnostics];
-  if (pending.authoringItem && !hasErrors(diagnostics)) {
-    const writer = writeQti3AssessmentItemResult(pending.authoringItem);
-    if (writer.ok) {
-      diagnostics.push(...validateWrittenXml(writer.xml));
-      return {
-        identifier: pending.identifier,
-        title: pending.title,
-        href,
-        authoringItem: pending.authoringItem,
-        xml: writer.xml,
-        diagnostics,
-      };
-    }
-    diagnostics.push({
-      code: "writer_diagnostics",
-      severity: "error",
-      message: "QTI 3 writer rejected migrated authoring item.",
-      writerDiagnostics: writer.diagnostics,
-    });
-  }
-
-  if (options.unsupportedPolicy === "stub") {
-    const stub = stubItem(pending.identifier, pending.title);
-    const writer = writeQti3AssessmentItemResult(stub);
-    return {
-      identifier: pending.identifier,
-      title: pending.title,
-      href,
-      authoringItem: stub,
-      xml: writer.ok ? writer.xml : undefined,
-      diagnostics: [
-        ...diagnostics,
-        diagnostic(
-          "unsupported_item_stubbed",
-          "warning",
-          "Unsupported item migrated as an extended-text review stub.",
-        ),
-      ],
-    };
-  }
-
-  return {
-    identifier: pending.identifier,
-    title: pending.title,
-    href,
-    authoringItem: options.unsupportedPolicy === "skip" ? undefined : pending.authoringItem,
-    diagnostics,
-  };
-}
-
-function validateWrittenXml(xml: string): QtiMigrationDiagnostic[] {
-  const parsed = parseQtiXml(xml);
-  const diagnostics: QtiMigrationDiagnostic[] = [];
-  if (!parsed.ok || !parsed.document) {
-    diagnostics.push(...coreDiagnostics("core_parse", parsed.diagnostics));
-    return diagnostics;
-  }
-  const validation = validateAssessmentItem(parsed.document);
-  if (!validation.ok) diagnostics.push(...coreDiagnostics("core_validate", validation.diagnostics));
-  return diagnostics;
-}
-
-function coreDiagnostics(
-  prefix: string,
-  diagnostics: readonly QtiDiagnostic[],
-): QtiMigrationDiagnostic[] {
-  return diagnostics.map((entry) =>
-    diagnostic(
-      `${prefix}.${entry.code}`,
-      entry.severity === "error" ? "error" : "warning",
-      entry.message,
-    ),
-  );
-}
-
-function stubItem(identifier: string, title: string): Qti3AuthoringItem {
-  return {
-    interactionType: "extendedText",
-    identifier,
-    title,
-    bodyHtml: qti3TrustedXmlFragment("<p>This item requires manual migration review.</p>"),
-    responseIdentifier: "RESPONSE",
-    responseBaseType: "string",
-    responseCardinality: "single",
-    expectedLines: 6,
-  };
-}
-
-function packageAssets(entries: readonly MigrationEntry[]): QtiMigrationAsset[] {
-  return entries
-    .filter((entry) => !entry.path.toLowerCase().endsWith(".xml"))
-    .map((entry) => ({
-      path: entry.path,
-      data: entry.bytes,
-      mediaType: detectPackageMediaType(entry.path),
-    }));
-}
-
 function partFromItems(
   identifier: string,
   title: string,
@@ -401,11 +260,3 @@ function partFromItems(
 ): QtiMigrationPart {
   return { identifier, title, itemHrefs: items.map((item) => item.href) };
 }
-
-function itemTitleFromXmlSafe(xml: string): string {
-  try {
-    return itemTitleFromXml(xml);
-  } catch {
-    return "Imported Item";
-  }
-}

package/src/item-finalize.ts

@@ -0,0 +1,133 @@
+import { parseQtiXml, validateAssessmentItem, type QtiDiagnostic } from "@longsightgroup/qti3-core";
+import {
+  qti3TrustedXmlFragment,
+  writeQti3AssessmentItemResult,
+  type Qti3AuthoringItem,
+} from "@longsightgroup/qti3-writer";
+
+import { diagnostic, hasErrors } from "./diagnostics.js";
+import { uniqueSiblingItemHref } from "./item-hrefs.js";
+import type { QtiMigrationDiagnostic, QtiMigrationItemResult } from "./types.js";
+import type { ResolvedQtiMigrationOptions } from "./types.js";
+
+export interface PendingMigrationItem {
+  readonly identifier: string;
+  readonly title: string;
+  readonly authoringItem?: Qti3AuthoringItem | undefined;
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+}
+
+export function finalizeItemResults(
+  pendingItems: readonly PendingMigrationItem[],
+  sourceHref: string,
+  options: ResolvedQtiMigrationOptions,
+): readonly QtiMigrationItemResult[] {
+  if (pendingItems.length <= 1) {
+    return pendingItems.map((item) => finalizeItemResult(item, sourceHref, options));
+  }
+
+  const identifiers = new Set<string>();
+  const paths = new Set<string>();
+  return pendingItems.map((item, index) => {
+    const identifier = item.identifier.trim();
+    const uniqueIdentifier = identifier && !identifiers.has(identifier);
+    if (uniqueIdentifier) identifiers.add(identifier);
+    const suffix = uniqueIdentifier ? identifier : `ITEM_${index + 1}`;
+    const href = uniqueSiblingItemHref(sourceHref, suffix, paths);
+    return finalizeItemResult(item, href, options);
+  });
+}
+
+export function finalizeItemResult(
+  pending: PendingMigrationItem,
+  href: string,
+  options: ResolvedQtiMigrationOptions,
+): QtiMigrationItemResult {
+  const diagnostics = [...pending.diagnostics];
+  if (pending.authoringItem && !hasErrors(diagnostics)) {
+    const writer = writeQti3AssessmentItemResult(pending.authoringItem);
+    if (writer.ok) {
+      diagnostics.push(...validateWrittenXml(writer.xml));
+      return {
+        identifier: pending.identifier,
+        title: pending.title,
+        href,
+        authoringItem: pending.authoringItem,
+        xml: writer.xml,
+        diagnostics,
+      };
+    }
+    diagnostics.push({
+      code: "writer_diagnostics",
+      severity: "error",
+      message: "QTI 3 writer rejected migrated authoring item.",
+      writerDiagnostics: writer.diagnostics,
+    });
+  }
+
+  if (options.unsupportedPolicy === "stub") {
+    const stub = stubItem(pending.identifier, pending.title);
+    const writer = writeQti3AssessmentItemResult(stub);
+    return {
+      identifier: pending.identifier,
+      title: pending.title,
+      href,
+      authoringItem: stub,
+      xml: writer.ok ? writer.xml : undefined,
+      diagnostics: [
+        ...diagnostics,
+        diagnostic(
+          "unsupported_item_stubbed",
+          "warning",
+          "Unsupported item migrated as an extended-text review stub.",
+        ),
+      ],
+    };
+  }
+
+  return {
+    identifier: pending.identifier,
+    title: pending.title,
+    href,
+    authoringItem: options.unsupportedPolicy === "skip" ? undefined : pending.authoringItem,
+    diagnostics,
+  };
+}
+
+function validateWrittenXml(xml: string): QtiMigrationDiagnostic[] {
+  const parsed = parseQtiXml(xml);
+  const diagnostics: QtiMigrationDiagnostic[] = [];
+  if (!parsed.ok || !parsed.document) {
+    diagnostics.push(...coreDiagnostics("core_parse", parsed.diagnostics));
+    return diagnostics;
+  }
+  const validation = validateAssessmentItem(parsed.document);
+  if (!validation.ok) diagnostics.push(...coreDiagnostics("core_validate", validation.diagnostics));
+  return diagnostics;
+}
+
+function coreDiagnostics(
+  prefix: string,
+  diagnostics: readonly QtiDiagnostic[],
+): QtiMigrationDiagnostic[] {
+  return diagnostics.map((entry) =>
+    diagnostic(
+      `${prefix}.${entry.code}`,
+      entry.severity === "error" ? "error" : "warning",
+      entry.message,
+    ),
+  );
+}
+
+function stubItem(identifier: string, title: string): Qti3AuthoringItem {
+  return {
+    interactionType: "extendedText",
+    identifier,
+    title,
+    bodyHtml: qti3TrustedXmlFragment("<p>This item requires manual migration review.</p>"),
+    responseIdentifier: "RESPONSE",
+    responseBaseType: "string",
+    responseCardinality: "single",
+    expectedLines: 6,
+  };
+}

package/src/item-hrefs.ts

@@ -0,0 +1,23 @@
+import { migrationPathIdentifier } from "./identifiers.js";
+
+export function uniqueSiblingItemHref(
+  sourceHref: string,
+  suffix: string,
+  usedPaths: Set<string>,
+): string {
+  const slashIndex = sourceHref.lastIndexOf("/");
+  const directory = slashIndex >= 0 ? sourceHref.slice(0, slashIndex + 1) : "";
+  const fileName = slashIndex >= 0 ? sourceHref.slice(slashIndex + 1) : sourceHref;
+  const dotIndex = fileName.toLowerCase().endsWith(".xml")
+    ? fileName.length - 4
+    : fileName.lastIndexOf(".");
+  const baseName = dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName || "item";
+  const extension = dotIndex > 0 ? fileName.slice(dotIndex) : ".xml";
+  const safeSuffix = migrationPathIdentifier(suffix);
+  let candidate = `${directory}${baseName}_${safeSuffix}${extension}`;
+  for (let index = 2; usedPaths.has(candidate); index += 1) {
+    candidate = `${directory}${baseName}_${safeSuffix}_${index}${extension}`;
+  }
+  usedPaths.add(candidate);
+  return candidate;
+}

package/src/migrate-items.ts

@@ -0,0 +1,39 @@
+import { migrationPathIdentifier } from "./identifiers.js";
+import type { PendingMigrationItem } from "./item-finalize.js";
+import { migrateQti12Xml } from "./qti12-item.js";
+import { itemTitleFromXml, migrateQti2ItemXml } from "./qti2-item.js";
+import type { QtiMigrationSourceFormat } from "./types.js";
+import type { ResolvedQtiMigrationOptions } from "./types.js";
+
+export function migrateItemXml(
+  xml: string,
+  path: string,
+  sourceFormat: QtiMigrationSourceFormat,
+  options: ResolvedQtiMigrationOptions,
+): readonly PendingMigrationItem[] {
+  if (sourceFormat === "qti12") {
+    return migrateQti12Xml(xml, path, options).map((result, index) => ({
+      identifier: result.authoringItem?.identifier ?? `ITEM_${index + 1}`,
+      title: result.authoringItem?.title ?? itemTitleFromXmlSafe(xml),
+      authoringItem: result.authoringItem,
+      diagnostics: result.diagnostics,
+    }));
+  }
+  const result = migrateQti2ItemXml(xml, path, sourceFormat, options);
+  return [
+    {
+      identifier: result.authoringItem?.identifier ?? migrationPathIdentifier(path),
+      title: result.authoringItem?.title ?? itemTitleFromXmlSafe(xml),
+      authoringItem: result.authoringItem,
+      diagnostics: result.diagnostics,
+    },
+  ];
+}
+
+export function itemTitleFromXmlSafe(xml: string): string {
+  try {
+    return itemTitleFromXml(xml);
+  } catch {
+    return "Imported Item";
+  }
+}

package/src/package-result.ts

@@ -1,14 +1,25 @@
+import { detectPackageMediaType } from "@longsightgroup/qti3-core";
 import type { Qti3PackageAsset, Qti3PackageItem } from "@longsightgroup/qti3-writer";
+import { writeQti3PackageFilesResult } from "@longsightgroup/qti3-writer";
 
 import { diagnostic, hasErrors } from "./diagnostics.js";
 import { migrationPackageIdentifier } from "./identifiers.js";
 import type {
   QtiMigrationAsset,
   QtiMigrationDiagnostic,
+  QtiMigrationResourceEntry,
   QtiMigrationResult,
   QtiPackageMigrationResult,
 } from "./types.js";
 
+export type MigrationPackageEntriesResult =
+  | {
+      readonly ok: true;
+      readonly entries: readonly QtiMigrationResourceEntry[];
+      readonly diagnostics: readonly QtiMigrationDiagnostic[];
+    }
+  | { readonly ok: false; readonly diagnostics: readonly QtiMigrationDiagnostic[] };
+
 export function migrationResultToPackage(result: QtiMigrationResult): QtiPackageMigrationResult {
   const itemDiagnostics = result.items.flatMap((item) => item.diagnostics);
   const assetDiagnostics: QtiMigrationDiagnostic[] = [];
@@ -34,6 +45,41 @@ export function migrationResultToPackage(result: QtiMigrationResult): QtiPackage
   };
 }
 
+export function migrationResultToPackageEntries(
+  result: QtiMigrationResult,
+): MigrationPackageEntriesResult {
+  const packageResult = migrationResultToPackage(result);
+  if (!packageResult.ok) {
+    return { ok: false, diagnostics: packageResult.diagnostics };
+  }
+
+  const files = writeQti3PackageFilesResult(packageResult.package);
+  if (!files.ok) {
+    return {
+      ok: false,
+      diagnostics: [
+        ...packageResult.diagnostics,
+        {
+          code: "writer_diagnostics",
+          severity: "error",
+          message: "QTI 3 writer rejected migrated package files.",
+          writerDiagnostics: files.diagnostics,
+        },
+      ],
+    };
+  }
+
+  return {
+    ok: true,
+    entries: files.files.map((file) => ({
+      path: file.path,
+      data: file.data,
+      mediaType: detectPackageMediaType(file.path),
+    })),
+    diagnostics: packageResult.diagnostics,
+  };
+}
+
 function buildPackageItems(
   result: QtiMigrationResult,
   assetsByPath: ReadonlyMap<string, Qti3PackageAsset>,

package/src/paths.ts

@@ -0,0 +1,33 @@
+import { normalizePackagePath, type QtiDiagnostic } from "@longsightgroup/qti3-core";
+
+import { diagnostic } from "./diagnostics.js";
+import type { QtiMigrationDiagnostic } from "./types.js";
+
+/** Normalize a host resource path and map core package-path diagnostics into migrator codes. */
+export function normalizeMigrationResourcePath(
+  path: string,
+  context: string,
+  diagnostics: QtiMigrationDiagnostic[],
+): string | undefined {
+  const coreDiagnostics: QtiDiagnostic[] = [];
+  const normalized = normalizePackagePath(path.replaceAll("\\", "/"), context, coreDiagnostics);
+  diagnostics.push(
+    ...coreDiagnostics.map((entry) =>
+      diagnostic(
+        `resource_${entry.code}`,
+        entry.severity === "error" ? "error" : "warning",
+        entry.message,
+        {
+          path: entry.path,
+        },
+      ),
+    ),
+  );
+  if (normalized === "") {
+    diagnostics.push(
+      diagnostic("resource_path_empty", "error", `${context} must not be empty.`, { path }),
+    );
+    return undefined;
+  }
+  return normalized;
+}