@longsightgroup/qti3-core 0.7.2 → 0.8.0

package/src/validation.ts

@@ -21,11 +21,7 @@ import type {
   QtiValue,
   QtiValidationResult,
 } from "./types.js";
-import {
-  validateSharedVocabularyExtendedText,
-  validateSharedVocabularyInputWidth,
-  validateSharedVocabularyMediaPlayerControls,
-} from "./shared-vocabulary-validation.js";
+import { validateInteractionSharedVocabulary } from "./shared-vocabulary-interaction-validation.js";
 import { isValidQtiPatternMask } from "./pattern-mask.js";
 import { validateQtiDataSsmlMetadata } from "./tts.js";
 import { qtiValueToStringList } from "./value-format.js";
@@ -45,6 +41,7 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
   validateInteractions(item, diagnostics);
   validateModalFeedback(item, diagnostics);
   validateCatalogInfo(item, diagnostics);
+  validateCompanionMaterials(item, diagnostics);
   validateStylesheets(item, diagnostics);
   diagnostics.push(...validateQtiDataSsmlMetadata(item));
   validateResponseProcessingTemplate(item, diagnostics);
@@ -716,6 +713,37 @@ function validateOutcomeLookupTables(item: QtiAssessmentItem, diagnostics: QtiDi
   }
 }
 
+function validateCompanionMaterials(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
+  const companionMaterials = item.companionMaterials;
+  if (!companionMaterials) return;
+
+  for (const child of companionMaterials.unparsedChildren) {
+    if (child.qtiName === "qti-physical-material") {
+      diagnostics.push({
+        code: "companionMaterials.model.inconsistent",
+        severity: "error",
+        message:
+          "Empty qti-physical-material must be represented as a parse warning, not an unparsed child.",
+        path: child.source?.path,
+        source: child.source,
+      });
+    }
+  }
+
+  for (const material of companionMaterials.physicalMaterials) {
+    if (material.text.trim().length === 0) {
+      diagnostics.push({
+        code: "companionMaterials.physicalMaterial.empty.model",
+        severity: "error",
+        message:
+          "qti-physical-material requires non-empty text content in the parsed companion materials model.",
+        path: material.source?.path,
+        source: material.source,
+      });
+    }
+  }
+}
+
 function validateStylesheets(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
   for (const stylesheet of item.stylesheets) {
     if (stylesheet.href.trim().length > 0) continue;
@@ -1692,342 +1720,6 @@ function validateInteractions(item: QtiAssessmentItem, diagnostics: QtiDiagnosti
   }
 }
 
-function validateInteractionSharedVocabulary(
-  interaction: QtiInteraction,
-  diagnostics: QtiDiagnostic[],
-): void {
-  if (
-    interaction.type !== "choice" &&
-    interaction.type !== "match" &&
-    interaction.type !== "gapMatch" &&
-    interaction.type !== "graphicGapMatch" &&
-    interaction.type !== "inlineChoice" &&
-    interaction.type !== "textEntry" &&
-    interaction.type !== "extendedText" &&
-    interaction.type !== "media" &&
-    interaction.type !== "order"
-  ) {
-    return;
-  }
-  const classNames = sharedClassNames(interaction.attributes);
-  const classNameSet = new Set(classNames);
-  if (interaction.type === "media") {
-    validateMediaInteractionSharedVocabulary(interaction, diagnostics);
-    return;
-  }
-
-  if (interaction.type === "inlineChoice" || interaction.type === "textEntry") {
-    validateInteractionInputWidthSharedVocabulary(interaction, classNames, diagnostics);
-    return;
-  }
-
-  if (interaction.type === "extendedText") {
-    diagnostics.push(
-      ...validateSharedVocabularyExtendedText({
-        classNames,
-        subjectQtiName: interaction.qtiName,
-        expectedLength: interaction.attributes["expected-length"],
-        path: interaction.source?.path,
-        source: interaction.source,
-      }),
-    );
-    return;
-  }
-
-  if (interaction.type === "choice" || interaction.type === "order") {
-    validateSharedVocabularyLabelClasses(interaction, classNames, diagnostics);
-  }
-
-  if (
-    interaction.type === "match" ||
-    interaction.type === "gapMatch" ||
-    interaction.type === "graphicGapMatch"
-  ) {
-    if (interaction.type === "match") {
-      validateMatchInteractionSharedVocabulary(interaction, classNames, diagnostics);
-    }
-    validateChoicesPositionSharedVocabulary(interaction, classNames, diagnostics);
-    validateChoicesContainerWidthSharedVocabulary(interaction, diagnostics);
-    if (interaction.type === "gapMatch") {
-      validateGapInputWidthSharedVocabulary(interaction, diagnostics);
-    }
-    return;
-  }
-
-  if (interaction.type === "order") {
-    validateOrderInteractionSharedVocabulary(interaction, classNames, classNameSet, diagnostics);
-    return;
-  }
-
-  validateOrientationSharedVocabulary(interaction, classNameSet, diagnostics);
-
-  const validStackingClasses = new Set<string>();
-  const invalidStackingClasses = new Set<string>();
-  for (const className of classNames) {
-    const stacking = /^qti-choices-stacking-(\d+)$/.exec(className)?.[1];
-    if (stacking === undefined) continue;
-    const count = Number(stacking);
-    if (count >= 1 && count <= 5) validStackingClasses.add(className);
-    else invalidStackingClasses.add(className);
-  }
-
-  if (validStackingClasses.size > 1) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.stackingConflict",
-      severity: "warning",
-      message: `qti-choice-interaction should not include multiple qti-choices-stacking-* classes: ${[...validStackingClasses].join(", ")}. The first valid stacking class in class attribute order takes precedence at runtime.`,
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-
-  for (const className of invalidStackingClasses) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.stackingInvalid",
-      severity: "warning",
-      message: `qti-choice-interaction shared vocabulary class ${className} is not supported; expected qti-choices-stacking-1 through qti-choices-stacking-5.`,
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-}
-
-function validateSharedVocabularyLabelClasses(
-  interaction: QtiInteraction,
-  classNames: string[],
-  diagnostics: QtiDiagnostic[],
-): void {
-  const labelClasses = classNames.filter((className) =>
-    [
-      "qti-labels-decimal",
-      "qti-labels-cjk-ideographic",
-      "qti-labels-lower-alpha",
-      "qti-labels-upper-alpha",
-    ].includes(className),
-  );
-  if (new Set(labelClasses).size > 1) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.labelsConflict",
-      severity: "warning",
-      message: `${interaction.qtiName} should not include multiple qti-labels-* style classes: ${[...new Set(labelClasses)].join(", ")}. qti-labels-decimal takes precedence over qti-labels-cjk-ideographic, then qti-labels-lower-alpha, then qti-labels-upper-alpha at runtime.`,
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-
-  const suffixClasses = classNames.filter((className) =>
-    [
-      "qti-labels-suffix-none",
-      "qti-labels-suffix-period",
-      "qti-labels-suffix-parenthesis",
-    ].includes(className),
-  );
-  if (new Set(suffixClasses).size <= 1) return;
-  diagnostics.push({
-    code: "interaction.sharedVocabulary.labelSuffixConflict",
-    severity: "warning",
-    message: `${interaction.qtiName} should not include multiple qti-labels-suffix-* classes: ${[...new Set(suffixClasses)].join(", ")}. qti-labels-suffix-none takes precedence over qti-labels-suffix-period, then qti-labels-suffix-parenthesis at runtime.`,
-    path: interaction.source?.path,
-    source: interaction.source,
-  });
-}
-
-function validateOrientationSharedVocabulary(
-  interaction: QtiInteraction,
-  classNameSet: Set<string>,
-  diagnostics: QtiDiagnostic[],
-): void {
-  if (
-    !classNameSet.has("qti-orientation-horizontal") ||
-    !classNameSet.has("qti-orientation-vertical")
-  ) {
-    return;
-  }
-  diagnostics.push({
-    code: "interaction.sharedVocabulary.orientationConflict",
-    severity: "warning",
-    message: `${interaction.qtiName} should not include both qti-orientation-horizontal and qti-orientation-vertical; qti-orientation-horizontal takes precedence at runtime.`,
-    path: interaction.source?.path,
-    source: interaction.source,
-  });
-}
-
-function validateOrderInteractionSharedVocabulary(
-  interaction: QtiInteraction,
-  classNames: string[],
-  classNameSet: Set<string>,
-  diagnostics: QtiDiagnostic[],
-): void {
-  validateOrientationSharedVocabulary(interaction, classNameSet, diagnostics);
-  validateChoicesPositionSharedVocabulary(interaction, classNames, diagnostics);
-  validateChoicesContainerWidthSharedVocabulary(interaction, diagnostics);
-}
-
-const SHARED_VOCABULARY_CHOICES_POSITION_CLASSES = [
-  "qti-choices-top",
-  "qti-choices-bottom",
-  "qti-choices-left",
-  "qti-choices-right",
-] as const;
-
-function validateMatchInteractionSharedVocabulary(
-  interaction: QtiInteraction,
-  classNames: string[],
-  diagnostics: QtiDiagnostic[],
-): void {
-  const hasTabular = classNames.includes("qti-match-tabular");
-  const hasHeaderHidden = classNames.includes("qti-header-hidden");
-  const firstColumnHeader = interaction.attributes["data-first-column-header"];
-  if (!hasTabular && (hasHeaderHidden || firstColumnHeader !== undefined)) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.matchTabularContext",
-      severity: "warning",
-      message:
-        "qti-match-interaction shared vocabulary class qti-header-hidden and data-first-column-header are only relevant when qti-match-tabular is specified; they are ignored at runtime.",
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-  if (hasTabular && hasHeaderHidden && firstColumnHeader !== undefined) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.matchTabularHeaderHidden",
-      severity: "warning",
-      message:
-        "qti-match-interaction data-first-column-header is ignored when qti-header-hidden suppresses the tabular header row.",
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-  if (!hasTabular) return;
-
-  const choicesPositionClasses = classNames.filter((className) =>
-    SHARED_VOCABULARY_CHOICES_POSITION_CLASSES.includes(
-      className as (typeof SHARED_VOCABULARY_CHOICES_POSITION_CLASSES)[number],
-    ),
-  );
-  if (
-    choicesPositionClasses.length > 0 ||
-    interaction.attributes["data-choices-container-width"] !== undefined
-  ) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.matchTabularChoicesConflict",
-      severity: "warning",
-      message:
-        "qti-match-interaction qti-match-tabular uses a matrix layout; qti-choices-* position classes and data-choices-container-width are ignored at runtime.",
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-  if (!hasHeaderHidden && (firstColumnHeader === undefined || firstColumnHeader === "")) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.matchTabularFirstColumnHeader",
-      severity: "warning",
-      message:
-        "qti-match-interaction with qti-match-tabular should specify data-first-column-header for the top-left table header when the tabular header row is shown.",
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-}
-
-function validateChoicesPositionSharedVocabulary(
-  interaction: QtiInteraction,
-  classNames: string[],
-  diagnostics: QtiDiagnostic[],
-): void {
-  const choicesPositionClasses = classNames.filter((className) =>
-    SHARED_VOCABULARY_CHOICES_POSITION_CLASSES.includes(
-      className as (typeof SHARED_VOCABULARY_CHOICES_POSITION_CLASSES)[number],
-    ),
-  );
-  if (new Set(choicesPositionClasses).size > 1) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.orderChoicesPositionConflict",
-      severity: "warning",
-      message: `${interaction.qtiName} should not include multiple qti-choices-* position classes: ${[...new Set(choicesPositionClasses)].join(", ")}. The first position class in class attribute order takes precedence at runtime.`,
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-}
-
-function validateChoicesContainerWidthSharedVocabulary(
-  interaction: QtiInteraction,
-  diagnostics: QtiDiagnostic[],
-): void {
-  const width = interaction.attributes["data-choices-container-width"];
-  if (width === undefined) return;
-  const parsed = Number(width);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    diagnostics.push({
-      code: "interaction.sharedVocabulary.orderChoicesContainerWidth",
-      severity: "warning",
-      message: `${interaction.qtiName} data-choices-container-width must be a positive pixel value; the invalid value is ignored at runtime.`,
-      path: interaction.source?.path,
-      source: interaction.source,
-    });
-  }
-}
-
-function validateGapInputWidthSharedVocabulary(
-  interaction: QtiInteraction,
-  diagnostics: QtiDiagnostic[],
-): void {
-  for (const gap of interaction.choices.filter((choice) => choice.qtiName === "qti-gap")) {
-    diagnostics.push(
-      ...validateSharedVocabularyInputWidth({
-        classNames: sharedClassNames(gap.attributes),
-        subjectQtiName: "qti-gap",
-        path: gap.source?.path ?? interaction.source?.path,
-        source: gap.source ?? interaction.source,
-        conflictCode: "interaction.sharedVocabulary.gapInputWidthConflict",
-        invalidCode: "interaction.sharedVocabulary.gapInputWidthInvalid",
-      }),
-    );
-  }
-}
-
-function validateInteractionInputWidthSharedVocabulary(
-  interaction: QtiInteraction,
-  classNames: string[],
-  diagnostics: QtiDiagnostic[],
-): void {
-  diagnostics.push(
-    ...validateSharedVocabularyInputWidth({
-      classNames,
-      subjectQtiName: interaction.qtiName,
-      path: interaction.source?.path,
-      source: interaction.source,
-      conflictCode: "interaction.sharedVocabulary.inputWidthConflict",
-      invalidCode: "interaction.sharedVocabulary.inputWidthInvalid",
-    }),
-  );
-}
-
-function validateMediaInteractionSharedVocabulary(
-  interaction: QtiInteraction,
-  diagnostics: QtiDiagnostic[],
-): void {
-  diagnostics.push(
-    ...validateSharedVocabularyMediaPlayerControls({
-      value: interaction.attributes["data-qti-media-player-controls"],
-      subjectQtiName: interaction.qtiName,
-      path: interaction.source?.path,
-      source: interaction.source,
-    }),
-  );
-
-  if (!interaction.object) return;
-  diagnostics.push(
-    ...validateSharedVocabularyMediaPlayerControls({
-      value: interaction.object.attributes["data-qti-media-player-controls"],
-      subjectQtiName: `${interaction.qtiName} media object`,
-      path: interaction.object.source?.path ?? interaction.source?.path,
-      source: interaction.object.source ?? interaction.source,
-    }),
-  );
-}
-
 function sharedClassNames(attributes: Record<string, string>): string[] {
   return (attributes.class ?? "").split(/\s+/).filter(Boolean);
 }