@longsightgroup/qti3-migrator 0.9.6 → 0.9.8

package/src/resource-migration.ts

@@ -0,0 +1,197 @@
+import { decodeUtf8 } from "@longsightgroup/qti3-core";
+
+import { migrationPackageAssets, resourceClosureAssetHrefs } from "./assets.js";
+import { aggregateMigrationDiagnostics, diagnostic } from "./diagnostics.js";
+import { finalizeItemResults } from "./item-finalize.js";
+import { migrateItemXml } from "./migrate-items.js";
+import { normalizeMigrationResourcePath } from "./paths.js";
+import { migrationResultToPackageEntries } from "./package-result.js";
+import { resolveOptions } from "./options.js";
+import {
+  detectMigrationSource,
+  migrationEntriesFromFileMap,
+  type MigrationSource,
+} from "./source.js";
+import type {
+  QtiMigrationDiagnostic,
+  QtiMigrationOptions,
+  QtiMigrationPart,
+  QtiMigrationResourceInput,
+  QtiMigrationResult,
+  QtiMigrationSourceFormat,
+  QtiResourceMigrationResult,
+} from "./types.js";
+
+interface NormalizedResourceInput {
+  readonly sourcePath: string;
+  readonly entries: ReturnType<typeof migrationEntriesFromFileMap>["entries"];
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+}
+
+/** Migrate one QTI resource and its local file closure into launchable QTI 3 package entries. */
+export async function migrateQtiResourceToQti3(
+  input: QtiMigrationResourceInput,
+  options: QtiMigrationOptions = {},
+): Promise<QtiResourceMigrationResult> {
+  const resolvedOptions = resolveOptions(options);
+  const normalized = normalizeResourceInput(input);
+  if (normalized.diagnostics.length) {
+    return failedResourceMigrationResult({
+      title: input.title ?? input.sourcePath,
+      diagnostics: normalized.diagnostics,
+    });
+  }
+
+  const sourceEntry = normalized.entries.find((entry) => entry.path === normalized.sourcePath);
+  if (!sourceEntry) {
+    return failedResourceMigrationResult({
+      title: input.title ?? normalized.sourcePath,
+      diagnostics: [
+        diagnostic(
+          "resource_source_missing",
+          "error",
+          `QTI resource source path ${normalized.sourcePath} was not found in the resource files.`,
+          { path: normalized.sourcePath },
+        ),
+      ],
+    });
+  }
+
+  const sourceXml = decodeUtf8(sourceEntry.bytes);
+  const source: MigrationSource = {
+    filename: normalized.sourcePath,
+    isPackage: false,
+    entries: [],
+    xml: sourceXml,
+  };
+  const detection = detectMigrationSource(source);
+  if (!detection.supported || !detection.sourceFormat) {
+    return failedResourceMigrationResult({
+      title: input.title ?? normalized.sourcePath,
+      sourceFormat: detection.sourceFormat,
+      diagnostics: [
+        diagnostic(
+          "source_unsupported",
+          "error",
+          `Unsupported QTI migration source: ${detection.reason}.`,
+          { path: normalized.sourcePath, sourceFormat: detection.sourceFormat },
+        ),
+      ],
+    });
+  }
+
+  const assetHrefs = resourceClosureAssetHrefs(normalized.entries);
+  const items = finalizeItemResults(
+    migrateItemXml(sourceXml, normalized.sourcePath, detection.sourceFormat, resolvedOptions),
+    normalized.sourcePath,
+    resolvedOptions,
+  ).map((item) => ({ ...item, assetHrefs }));
+
+  const migration: QtiMigrationResult = {
+    title: input.title ?? items[0]?.title ?? normalized.sourcePath,
+    sourceFormat: detection.sourceFormat,
+    parts: [partFromItems("PART_1", input.title ?? "Imported Resource", items)],
+    items,
+    assets: migrationPackageAssets(normalized.entries),
+    diagnostics: [],
+  };
+
+  const packageEntries = migrationResultToPackageEntries(migration);
+  if (!packageEntries.ok) {
+    return failedResourceMigrationResult({
+      title: migration.title,
+      sourceFormat: detection.sourceFormat,
+      migration,
+      diagnostics: aggregateMigrationDiagnostics(migration, packageEntries.diagnostics),
+    });
+  }
+
+  const diagnostics = aggregateMigrationDiagnostics(migration, packageEntries.diagnostics);
+  const itemHrefs = items.map((item) => item.href);
+  const launchHref = itemHrefs[0];
+  if (!launchHref) {
+    return failedResourceMigrationResult({
+      title: migration.title,
+      sourceFormat: detection.sourceFormat,
+      migration,
+      diagnostics: [
+        ...diagnostics,
+        diagnostic(
+          "resource_launch_href_missing",
+          "error",
+          "Migrated resource did not produce a launchable item path.",
+          { path: normalized.sourcePath, sourceFormat: detection.sourceFormat },
+        ),
+      ],
+    });
+  }
+
+  return {
+    ok: true,
+    title: migration.title,
+    status: diagnostics.some((entry) => entry.severity === "warning")
+      ? "converted_with_warnings"
+      : "converted",
+    sourceFormat: detection.sourceFormat,
+    launchHref,
+    itemHrefs,
+    entries: packageEntries.entries,
+    diagnostics,
+  };
+}
+
+function normalizeResourceInput(input: QtiMigrationResourceInput): NormalizedResourceInput {
+  const diagnostics: QtiMigrationDiagnostic[] = [];
+  const sourcePath = normalizeMigrationResourcePath(
+    input.sourcePath,
+    "resource source path",
+    diagnostics,
+  );
+  const { entries, diagnostics: entryDiagnostics } = migrationEntriesFromFileMap(
+    input.files,
+    (path) => normalizeMigrationResourcePath(path, "resource file path", diagnostics),
+  );
+  return {
+    sourcePath: sourcePath ?? input.sourcePath.replaceAll("\\", "/"),
+    entries,
+    diagnostics: [...diagnostics, ...entryDiagnostics],
+  };
+}
+
+function partFromItems(
+  identifier: string,
+  title: string,
+  items: QtiMigrationResult["items"],
+): QtiMigrationPart {
+  return { identifier, title, itemHrefs: items.map((item) => item.href) };
+}
+
+function failedResourceMigrationResult(options: {
+  readonly title: string;
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+  readonly sourceFormat?: QtiMigrationSourceFormat | undefined;
+  readonly migration?: QtiMigrationResult | undefined;
+}): QtiResourceMigrationResult {
+  const migration =
+    options.migration ??
+    ({
+      title: options.title,
+      sourceFormat: options.sourceFormat,
+      parts: [],
+      items: [],
+      assets: [],
+      diagnostics: options.diagnostics,
+    } satisfies QtiMigrationResult);
+  return {
+    ok: false,
+    title: migration.title,
+    status: "failed",
+    sourceFormat: options.sourceFormat ?? migration.sourceFormat,
+    itemHrefs: migration.items.map((item) => item.href),
+    entries: [],
+    diagnostics: options.diagnostics.length
+      ? options.diagnostics
+      : aggregateMigrationDiagnostics(migration),
+    migration,
+  };
+}

package/src/source.ts

@@ -21,6 +21,44 @@ export interface MigrationSource {
   readonly xml?: string | undefined;
 }
 
+export function buildMigrationEntry(path: string, bytes: Uint8Array): MigrationEntry {
+  return {
+    path,
+    bytes,
+    text: isMigrationTextPath(path) ? decodeUtf8(bytes) : undefined,
+  };
+}
+
+export function migrationEntriesFromFileMap(
+  files: Readonly<Record<string, Uint8Array>>,
+  normalizePath: (path: string) => string | undefined,
+): {
+  readonly entries: readonly MigrationEntry[];
+  readonly diagnostics: readonly QtiMigrationDiagnostic[];
+} {
+  const diagnostics: QtiMigrationDiagnostic[] = [];
+  const entries: MigrationEntry[] = [];
+  const seenPaths = new Set<string>();
+  for (const [path, bytes] of Object.entries(files)) {
+    const normalizedPath = normalizePath(path);
+    if (!normalizedPath) continue;
+    if (seenPaths.has(normalizedPath)) {
+      diagnostics.push(
+        diagnostic(
+          "resource_file_duplicate",
+          "error",
+          `Resource file path ${normalizedPath} is duplicated after normalization.`,
+          { path: normalizedPath },
+        ),
+      );
+      continue;
+    }
+    seenPaths.add(normalizedPath);
+    entries.push(buildMigrationEntry(normalizedPath, bytes));
+  }
+  return { entries, diagnostics };
+}
+
 export function readMigrationSource(input: QtiMigrationSourceInput): MigrationSource {
   if (input.xml !== undefined) {
     return { filename: input.filename, isPackage: false, entries: [], xml: input.xml };
@@ -32,11 +70,7 @@ export function readMigrationSource(input: QtiMigrationSourceInput): MigrationSo
     const unzipped = unzipSync(input.bytes);
     const entries = Object.entries(unzipped)
       .filter(([path]) => !path.endsWith("/"))
-      .map(([path, bytes]) => ({
-        path: path.replaceAll("\\", "/"),
-        bytes,
-        text: isTextPath(path) ? decodeUtf8(bytes) : undefined,
-      }));
+      .map(([path, bytes]) => buildMigrationEntry(path.replaceAll("\\", "/"), bytes));
     return { filename: input.filename, isPackage: true, entries };
   }
   return {
@@ -246,6 +280,6 @@ function isZip(bytes: Uint8Array): boolean {
   return bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b;
 }
 
-function isTextPath(path: string): boolean {
+function isMigrationTextPath(path: string): boolean {
   return /\.(xml|html?|txt|json|css|js)$/i.test(path);
 }

package/src/types.ts

@@ -1,4 +1,8 @@
-import type { Qti3AuthoringItem, Qti3WriterDiagnostic } from "@longsightgroup/qti3-writer";
+import type {
+  Qti3AuthoringItem,
+  Qti3PackageAuthoringInput,
+  Qti3WriterDiagnostic,
+} from "@longsightgroup/qti3-writer";
 
 export type QtiMigrationSourceFormat = "qti12" | "qti21" | "qti22";
 
@@ -13,6 +17,13 @@ export interface QtiMigrationSourceInput {
   readonly mime?: string | undefined;
 }
 
+/** Local file closure for migrating one QTI resource from a larger host package. */
+export interface QtiMigrationResourceInput {
+  readonly sourcePath: string;
+  readonly files: Readonly<Record<string, Uint8Array>>;
+  readonly title?: string | undefined;
+}
+
 export interface QtiMigrationOptions {
   readonly repairPolicy?: QtiMigrationRepairPolicy | undefined;
   readonly unsupportedPolicy?: QtiMigrationUnsupportedPolicy | undefined;
@@ -58,6 +69,7 @@ export interface QtiMigrationItemResult {
   readonly identifier: string;
   readonly title: string;
   readonly href: string;
+  readonly assetHrefs?: readonly string[] | undefined;
   readonly authoringItem?: Qti3AuthoringItem | undefined;
   readonly xml?: string | undefined;
   readonly diagnostics: readonly QtiMigrationDiagnostic[];
@@ -71,3 +83,43 @@ export interface QtiMigrationResult {
   readonly assets: readonly QtiMigrationAsset[];
   readonly diagnostics: readonly QtiMigrationDiagnostic[];
 }
+
+/** File emitted by resource-level migration for host storage or packaging. */
+export interface QtiMigrationResourceEntry {
+  readonly path: string;
+  readonly data: Uint8Array | string;
+  readonly mediaType?: string | undefined;
+}
+
+export type QtiResourceMigrationStatus = "converted" | "converted_with_warnings" | "failed";
+
+export type QtiPackageMigrationResult =
+  | {
+      readonly ok: true;
+      readonly package: Qti3PackageAuthoringInput;
+      readonly diagnostics: readonly QtiMigrationDiagnostic[];
+    }
+  | { readonly ok: false; readonly diagnostics: readonly QtiMigrationDiagnostic[] };
+
+/** Result of migrating one host-package resource and its local file closure. */
+export type QtiResourceMigrationResult =
+  | {
+      readonly ok: true;
+      readonly title: string;
+      readonly status: "converted" | "converted_with_warnings";
+      readonly sourceFormat: QtiMigrationSourceFormat;
+      readonly launchHref: string;
+      readonly itemHrefs: readonly string[];
+      readonly entries: readonly QtiMigrationResourceEntry[];
+      readonly diagnostics: readonly QtiMigrationDiagnostic[];
+    }
+  | {
+      readonly ok: false;
+      readonly title: string;
+      readonly status: "failed";
+      readonly sourceFormat?: QtiMigrationSourceFormat | undefined;
+      readonly itemHrefs: readonly string[];
+      readonly entries: readonly QtiMigrationResourceEntry[];
+      readonly diagnostics: readonly QtiMigrationDiagnostic[];
+      readonly migration: QtiMigrationResult;
+    };