@longsightgroup/qti3-core 0.1.2 → 0.2.0

package/src/validation.ts

@@ -20,6 +20,7 @@ import type {
   QtiValue,
   QtiValidationResult,
 } from "./types.js";
+import { validateQtiDataSsmlMetadata } from "./tts.js";
 
 const BUILT_IN_COMPLETION_STATUS = "completionStatus";
 
@@ -34,6 +35,7 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
   validateModalFeedback(item, diagnostics);
   validateCatalogInfo(item, diagnostics);
   validateStylesheets(item, diagnostics);
+  diagnostics.push(...validateQtiDataSsmlMetadata(item));
   validateProcessingReferences(item, diagnostics);
 
   return {
@@ -1443,7 +1445,9 @@ function validateInteractions(item: QtiAssessmentItem, diagnostics: QtiDiagnosti
     validateInteractionChoices(interaction, diagnostics);
     validateInteractionChildren(interaction, diagnostics);
     validateInteractionRequiredAttributes(interaction, diagnostics);
+    validatePortableCustomInteraction(interaction, item, diagnostics);
     validateInteractionLimitAttributes(interaction, diagnostics);
+    validateGraphicHotspotObjectDimensions(interaction, diagnostics);
     validateCorrectResponseReferences(
       interaction,
       interaction.responseIdentifier
@@ -1709,12 +1713,6 @@ function validateInteractionRequiredAttributes(
       "interaction.portableCustom.typeIdentifier",
       diagnostics,
     );
-    requireInteractionAttribute(
-      interaction,
-      "module",
-      "interaction.portableCustom.module",
-      diagnostics,
-    );
   }
 
   if (interaction.type === "slider") {
@@ -1800,6 +1798,116 @@ function requireInteractionAttribute(
   });
 }
 
+function validatePortableCustomInteraction(
+  interaction: QtiInteraction,
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (interaction.type !== "portableCustom") return;
+  const definition = interaction.portableCustom;
+  if (!definition) return;
+
+  const configuredModules = definition.interactionModules?.modules ?? [];
+  const hasModuleAttribute = Boolean(definition.module?.trim());
+  const hasConfiguredModule = configuredModules.some((module) => Boolean(module.id?.trim()));
+  if (!hasModuleAttribute && !hasConfiguredModule) {
+    diagnostics.push({
+      code: "interaction.portableCustom.module",
+      severity: "error",
+      message: `${interaction.qtiName} requires a module attribute or at least one qti-interaction-module id.`,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+
+  for (const module of configuredModules) {
+    if (!module.id?.trim()) {
+      diagnostics.push({
+        code: "interaction.portableCustom.moduleId",
+        severity: "error",
+        message: "qti-interaction-module requires a non-empty id.",
+        path: module.source?.path,
+        source: module.source,
+      });
+    }
+    warnExternalPortableCustomUrl(module.primaryPath, module.source, diagnostics);
+    warnExternalPortableCustomUrl(module.fallbackPath, module.source, diagnostics);
+  }
+
+  warnExternalPortableCustomUrl(
+    definition.interactionModules?.primaryConfiguration,
+    definition.interactionModules?.source,
+    diagnostics,
+  );
+  warnExternalPortableCustomUrl(
+    definition.interactionModules?.secondaryConfiguration,
+    definition.interactionModules?.source,
+    diagnostics,
+  );
+
+  const templateIdentifiers = new Set(
+    item.templateDeclarations.map((declaration) => declaration.identifier),
+  );
+  for (const variable of definition.templateVariables) {
+    if (!variable.identifier?.trim()) {
+      diagnostics.push({
+        code: "interaction.portableCustom.templateVariable",
+        severity: "error",
+        message: "qti-template-variable requires template-identifier or identifier.",
+        path: variable.source?.path,
+        source: variable.source,
+      });
+      continue;
+    }
+    if (!templateIdentifiers.has(variable.identifier)) {
+      diagnostics.push({
+        code: "interaction.portableCustom.templateVariable.reference",
+        severity: "error",
+        message: `qti-template-variable references missing template declaration ${variable.identifier}.`,
+        path: variable.source?.path,
+        source: variable.source,
+      });
+    }
+  }
+
+  for (const variable of definition.contextVariables) {
+    if (variable.identifier?.trim()) continue;
+    diagnostics.push({
+      code: "interaction.portableCustom.contextVariable",
+      severity: "error",
+      message: "qti-context-variable requires identifier.",
+      path: variable.source?.path,
+      source: variable.source,
+    });
+  }
+
+  for (const stylesheet of definition.stylesheets) {
+    if (stylesheet.href.trim().length > 0) continue;
+    diagnostics.push({
+      code: "stylesheet.href.required",
+      severity: "error",
+      message: "qti-stylesheet requires a non-empty href attribute.",
+      path: stylesheet.source?.path,
+      source: stylesheet.source,
+    });
+  }
+}
+
+function warnExternalPortableCustomUrl(
+  url: string | undefined,
+  source: QtiDiagnostic["source"],
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (!url || !/^https?:\/\//i.test(url)) return;
+  diagnostics.push({
+    code: "interaction.portableCustom.externalModuleUrl",
+    severity: "warning",
+    message: `Portable custom interaction module URL ${url} requires host delivery policy approval.`,
+    path: source?.path,
+    source,
+  });
+}
+
 function invalidNumber(
   interaction: QtiInteraction,
   attribute: string,
@@ -1922,6 +2030,97 @@ function validateHotspotGeometry(choice: QtiChoice, diagnostics: QtiDiagnostic[]
   }
 }
 
+function validateGraphicHotspotObjectDimensions(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (!usesGraphicHotspots(interaction)) return;
+  const hotspotChoices = interaction.choices.filter(isHotspotChoice);
+  if (hotspotChoices.length === 0) return;
+
+  const width = positiveDimension(interaction.object?.width);
+  const height = positiveDimension(interaction.object?.height);
+  if (width === undefined || height === undefined) {
+    diagnostics.push({
+      code: "interaction.graphicObjectDimensions",
+      severity: "warning",
+      message: `${interaction.qtiName} should declare object width and height so hotspot coords map to the rendered image.`,
+      path: interaction.object?.source?.path ?? interaction.source?.path,
+      source: interaction.object?.source ?? interaction.source,
+    });
+    return;
+  }
+
+  for (const choice of hotspotChoices) {
+    const bounds = hotspotBounds(choice);
+    if (!bounds) continue;
+    if (bounds.left >= 0 && bounds.top >= 0 && bounds.right <= width && bounds.bottom <= height) {
+      continue;
+    }
+    diagnostics.push({
+      code: "choice.coords.bounds",
+      severity: "warning",
+      message: `${choice.qtiName} ${choice.identifier} coords extend outside the ${width} by ${height} object image.`,
+      path: choice.source?.path,
+      source: choice.source,
+    });
+  }
+}
+
+function usesGraphicHotspots(interaction: QtiInteraction): boolean {
+  return (
+    interaction.type === "graphicOrder" ||
+    interaction.type === "graphicAssociate" ||
+    interaction.type === "graphicGapMatch" ||
+    interaction.type === "hotspot"
+  );
+}
+
+function isHotspotChoice(choice: QtiChoice): boolean {
+  return choice.qtiName === "qti-hotspot-choice" || choice.qtiName === "qti-associable-hotspot";
+}
+
+function positiveDimension(value: string | undefined): number | undefined {
+  if (!value || value.trim().endsWith("%")) return undefined;
+  const match = value.trim().match(/^(\d+(?:\.\d+)?|\.\d+)(?:px)?$/i);
+  if (!match?.[1]) return undefined;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function hotspotBounds(
+  choice: QtiChoice,
+): { left: number; top: number; right: number; bottom: number } | undefined {
+  const shape = choice.attributes.shape;
+  const coords = choice.attributes.coords;
+  if (!shape || !coords || !isHotspotShape(shape) || !isNumericCsv(coords)) return undefined;
+  const values = numericCsv(coords);
+  if (!hasValidShapeCoordinateCount(shape, values)) return undefined;
+
+  if (shape === "default") return undefined;
+  if (shape === "circle") {
+    const [x, y, radius] = values as [number, number, number];
+    return { left: x - radius, top: y - radius, right: x + radius, bottom: y + radius };
+  }
+  if (shape === "ellipse") {
+    const [x, y, radiusX, radiusY] = values as [number, number, number, number];
+    return { left: x - radiusX, top: y - radiusY, right: x + radiusX, bottom: y + radiusY };
+  }
+  if (shape === "rect") {
+    const [left, top, right, bottom] = values as [number, number, number, number];
+    return { left, top, right, bottom };
+  }
+
+  const xs = values.filter((_, index) => index % 2 === 0);
+  const ys = values.filter((_, index) => index % 2 === 1);
+  return {
+    left: Math.min(...xs),
+    top: Math.min(...ys),
+    right: Math.max(...xs),
+    bottom: Math.max(...ys),
+  };
+}
+
 function isHotspotShape(value: string): boolean {
   return (
     value === "circle" ||
@@ -2106,7 +2305,14 @@ function allowedInteractionChildren(interaction: QtiInteraction): Set<string> |
     case "extendedText":
       return new Set(common);
     case "portableCustom":
-      return setOf(common, ["qti-interaction-markup"]);
+      return setOf(common, [
+        "qti-interaction-markup",
+        "qti-interaction-modules",
+        "qti-template-variable",
+        "qti-context-variable",
+        "qti-stylesheet",
+        "qti-catalog-info",
+      ]);
     case "slider":
     case "textEntry":
     case "upload":
@@ -2206,7 +2412,22 @@ function expectedResponseShape(
   }
   if (interaction.type === "drawing") return { cardinalities: ["single"], baseTypes: ["file"] };
   if (interaction.type === "portableCustom") {
-    return { cardinalities: ["single"], baseTypes: ["string", "file", "uri"] };
+    return {
+      cardinalities: ["single", "multiple", "ordered", "record"],
+      baseTypes: [
+        "identifier",
+        "boolean",
+        "integer",
+        "float",
+        "string",
+        "point",
+        "pair",
+        "directedPair",
+        "duration",
+        "file",
+        "uri",
+      ],
+    };
   }
   return { cardinalities: ["single", "multiple"], baseTypes: ["identifier"] };
 }