@longsightgroup/qti3-core 0.9.3 → 0.9.5

package/src/response-input.ts

@@ -0,0 +1,19 @@
+/** One named response variable in record or array wire form. */
+export interface QtiNamedResponseInput {
+  identifier: string;
+  value: unknown;
+}
+
+export type QtiNamedResponsesInput =
+  | Record<string, unknown>
+  | readonly QtiNamedResponseInput[]
+  | undefined;
+
+/** Normalize record or array response payloads into a stable entry list. */
+export function listNamedResponseInputs(
+  responses: QtiNamedResponsesInput,
+): readonly QtiNamedResponseInput[] {
+  if (!responses) return [];
+  if (Array.isArray(responses)) return responses;
+  return Object.entries(responses).map(([identifier, value]) => ({ identifier, value }));
+}

package/src/response-validation-policy.ts

@@ -0,0 +1,226 @@
+import type { QtiChoice, QtiDiagnostic, QtiInteraction, QtiValue } from "./types.js";
+import { parseNonNegativeInteger } from "./validation-primitives.js";
+import { qtiValueToIdentifierList } from "./value-format.js";
+
+export interface QtiResponseValidationPolicy {
+  checkMinimum: boolean;
+  checkMaximum: boolean;
+  checkMatchMax: boolean;
+}
+
+export function responseIsEmpty(value: QtiValue): boolean {
+  return value === null || value === "" || (Array.isArray(value) && value.length === 0);
+}
+
+export function responseCount(value: QtiValue): number {
+  return responseIsEmpty(value) ? 0 : Array.isArray(value) ? value.length : 1;
+}
+
+/** Order and graphic order ignore max-choices unless min-choices is authored. */
+export function orderSubsetLimitsActive(interaction: QtiInteraction): boolean {
+  return (
+    (interaction.type === "order" || interaction.type === "graphicOrder") &&
+    interaction.attributes["min-choices"] !== undefined
+  );
+}
+
+export function responseLimitAttribute(
+  interaction: QtiInteraction,
+  choiceKey: "min-choices" | "max-choices",
+  associationKey: "min-associations" | "max-associations",
+): string | undefined {
+  if (interaction.type === "order" || interaction.type === "graphicOrder") {
+    return interaction.attributes[choiceKey];
+  }
+  return interaction.attributes[choiceKey] ?? interaction.attributes[associationKey];
+}
+
+function interactionRequiresResponse(interaction: QtiInteraction): boolean {
+  return interaction.attributes.required === "true";
+}
+
+export function minimumRequiredResponses(interaction: QtiInteraction | undefined): number {
+  if (!interaction) return 1;
+  if (interaction.type === "media") return minimumMediaPlays(interaction);
+  const explicit = responseLimitAttribute(interaction, "min-choices", "min-associations");
+  if (explicit === undefined) return interactionRequiresResponse(interaction) ? 1 : 0;
+  return parseNonNegativeInteger(explicit) ?? 1;
+}
+
+export function maximumAllowedResponses(
+  interaction: QtiInteraction | undefined,
+): number | undefined {
+  if (!interaction) return undefined;
+  if (interaction.type === "media") return maximumMediaPlays(interaction);
+  if (
+    (interaction.type === "order" || interaction.type === "graphicOrder") &&
+    !orderSubsetLimitsActive(interaction)
+  ) {
+    return undefined;
+  }
+  const explicit = responseLimitAttribute(interaction, "max-choices", "max-associations");
+  if (explicit === undefined) return undefined;
+  const parsed = parseNonNegativeInteger(explicit);
+  return parsed === undefined || parsed <= 0 ? undefined : parsed;
+}
+
+export function associationMaximumResponses(interaction: QtiInteraction): number | undefined {
+  return interaction.responseCardinality === "single" ? 1 : maximumAllowedResponses(interaction);
+}
+
+export function mediaPlayCount(value: QtiValue): number {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : 0;
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function minimumMediaPlays(interaction: QtiInteraction): number {
+  const parsed = parseNonNegativeInteger(interaction.attributes["min-plays"]);
+  if (parsed !== undefined) return parsed;
+  return interactionRequiresResponse(interaction) ? 1 : 0;
+}
+
+function maximumMediaPlays(interaction: QtiInteraction): number | undefined {
+  const parsed = parseNonNegativeInteger(interaction.attributes["max-plays"]);
+  return parsed === undefined || parsed <= 0 ? undefined : parsed;
+}
+
+export { maximumMediaPlays, minimumMediaPlays };
+
+export function responseValidationPolicy(
+  declaration: { readonly correctResponse: QtiValue | null },
+  interaction: QtiInteraction | undefined,
+): QtiResponseValidationPolicy {
+  const authoredMinimum =
+    interaction === undefined
+      ? undefined
+      : responseLimitAttribute(interaction, "min-choices", "min-associations");
+  const minimum = interaction === undefined ? undefined : minimumRequiredResponses(interaction);
+  const validatesMinimum =
+    declaration.correctResponse !== null ||
+    interaction?.type === "media" ||
+    authoredMinimum !== undefined ||
+    (minimum !== undefined && minimum > 0);
+  const maximum = maximumAllowedResponses(interaction);
+  if (
+    declaration.correctResponse === null &&
+    interaction?.type !== "media" &&
+    !validatesMinimum &&
+    maximum === undefined
+  ) {
+    return { checkMinimum: false, checkMaximum: false, checkMatchMax: false };
+  }
+  return {
+    checkMinimum: validatesMinimum,
+    checkMaximum: maximum !== undefined,
+    checkMatchMax: interaction !== undefined,
+  };
+}
+
+export function requiredResponseDiagnostic(
+  responseIdentifier: string,
+  interaction: QtiInteraction | undefined,
+  minimum: number,
+): QtiDiagnostic {
+  return {
+    code: "response.required",
+    severity: "error",
+    message:
+      interaction?.attributes["data-min-selections-message"] ??
+      (interaction?.type === "media"
+        ? `${responseIdentifier} requires at least ${minimum} play${minimum === 1 ? "" : "s"}.`
+        : minimum === 1
+          ? `${responseIdentifier} requires a response.`
+          : `${responseIdentifier} requires at least ${minimum} responses.`),
+    path: responseIdentifier,
+  };
+}
+
+export function maximumResponseDiagnostic(
+  responseIdentifier: string,
+  interaction: QtiInteraction | undefined,
+  maximum: number,
+): QtiDiagnostic {
+  return {
+    code: "response.maximum",
+    severity: "error",
+    message:
+      interaction?.attributes["data-max-selections-message"] ??
+      (interaction?.type === "media"
+        ? `${responseIdentifier} allows at most ${maximum} play${maximum === 1 ? "" : "s"}.`
+        : `${responseIdentifier} allows at most ${maximum} response${maximum === 1 ? "" : "s"}.`),
+    path: responseIdentifier,
+  };
+}
+
+export function parseUnlimitedMaximum(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = parseNonNegativeInteger(value);
+  return parsed === undefined || parsed <= 0 ? undefined : parsed;
+}
+
+export function choiceMatchMaximum(choice: QtiChoice): number | undefined {
+  return parseUnlimitedMaximum(choice.attributes["match-max"]);
+}
+
+export type DirectedPairUseSide = "source" | "target" | "either";
+
+export function directedPairChoiceUseCount(
+  choice: QtiChoice,
+  selectedPairs: string[],
+  side: DirectedPairUseSide = "either",
+): number {
+  return selectedPairs.reduce((count, pair) => {
+    const [source = "", target = ""] = pair.split(/\s+/);
+    if (side === "source") return source === choice.identifier ? count + 1 : count;
+    if (side === "target") return target === choice.identifier ? count + 1 : count;
+    return count + (source === choice.identifier ? 1 : 0) + (target === choice.identifier ? 1 : 0);
+  }, 0);
+}
+
+export function choiceMatchLimitExceeded(choice: QtiChoice, useCount: number): boolean {
+  const maximum = choiceMatchMaximum(choice);
+  return maximum !== undefined && useCount > maximum;
+}
+
+export function wouldExceedChoiceMatchMaximum(
+  choice: QtiChoice,
+  selectedPairs: string[],
+  side: DirectedPairUseSide = "either",
+): boolean {
+  return choiceMatchLimitExceeded(
+    choice,
+    directedPairChoiceUseCount(choice, selectedPairs, side) + 1,
+  );
+}
+
+function responseChoiceIdentifiers(response: QtiValue): string[] {
+  return qtiValueToIdentifierList(response).flatMap((value) => value.split(/\s+/).filter(Boolean));
+}
+
+export function matchMaxDiagnostics(
+  responseIdentifier: string,
+  interaction: QtiInteraction,
+  response: QtiValue,
+): QtiDiagnostic[] {
+  const identifiers = responseChoiceIdentifiers(response);
+  if (identifiers.length === 0) return [];
+  const counts = new Map<string, number>();
+  for (const identifier of identifiers) {
+    counts.set(identifier, (counts.get(identifier) ?? 0) + 1);
+  }
+
+  const diagnostics: QtiDiagnostic[] = [];
+  for (const choice of interaction.choices) {
+    const maximum = choiceMatchMaximum(choice);
+    if (maximum === undefined) continue;
+    const count = counts.get(choice.identifier) ?? 0;
+    if (count <= maximum) continue;
+    diagnostics.push({
+      code: "response.matchMax",
+      severity: "error",
+      message: `${choice.text || choice.identifier} may be used at most ${maximum} time${maximum === 1 ? "" : "s"}.`,
+      path: responseIdentifier,
+    });
+  }
+  return diagnostics;
+}

package/src/response-validation.ts

@@ -0,0 +1,298 @@
+import type {
+  QtiAssessmentItem,
+  QtiCardinality,
+  QtiDiagnostic,
+  QtiInteraction,
+  QtiResponseDeclaration,
+  QtiValue,
+} from "./types.js";
+import { assertNever } from "./assert-never.js";
+import { isNullResponse, isRecordValue } from "./processing-values.js";
+import { listNamedResponseInputs, type QtiNamedResponseInput } from "./response-input.js";
+import {
+  matchMaxDiagnostics,
+  maximumAllowedResponses,
+  maximumResponseDiagnostic,
+  mediaPlayCount,
+  minimumRequiredResponses,
+  requiredResponseDiagnostic,
+  responseCount,
+  responseLimitAttribute,
+  responseValidationPolicy,
+} from "./response-validation-policy.js";
+import { readQtiJsonValue } from "./value-format.js";
+
+export type { QtiNamedResponseInput as QtiResponseVariableInput } from "./response-input.js";
+export type QtiResponseVariablesInput = Record<string, unknown> | readonly QtiNamedResponseInput[];
+
+export type QtiResponseValidationDiagnosticCode =
+  | "response.required"
+  | "response.maximum"
+  | "response.matchMax"
+  | "response.cardinality"
+  | "response.undeclared"
+  | "response.identifier.required"
+  | "response.value.invalid";
+
+export interface QtiResponseValidationDiagnostic extends QtiDiagnostic {
+  code: QtiResponseValidationDiagnosticCode;
+  identifier?: string | undefined;
+}
+
+export interface QtiResponseValidationResult {
+  ok: boolean;
+  diagnostics: QtiResponseValidationDiagnostic[];
+}
+
+export interface QtiResponseValidationInput {
+  item: QtiAssessmentItem;
+  responses: QtiResponseVariablesInput;
+  allowIncompleteResponses?: boolean | undefined;
+  allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
+  responseIdentifiers?: Iterable<string> | undefined;
+}
+
+/** Validate submitted response variables against a parsed QTI assessment item. */
+export function validateQtiResponseVariables(
+  input: QtiResponseValidationInput,
+): QtiResponseValidationResult {
+  const diagnostics: QtiResponseValidationDiagnostic[] = [];
+  const declaredIdentifiers = new Set(
+    input.item.responseDeclarations.map((declaration) => declaration.identifier),
+  );
+  const allowedUndeclaredIdentifiers = new Set(input.allowedUndeclaredResponseIdentifiers ?? []);
+  const responses = ingestSubmittedResponses(
+    input.responses,
+    declaredIdentifiers,
+    allowedUndeclaredIdentifiers,
+    diagnostics,
+  );
+  const scopedResponseIdentifiers = input.responseIdentifiers
+    ? new Set(input.responseIdentifiers)
+    : undefined;
+  const interactionsByResponse = indexInteractionsByResponse(input.item.interactions);
+
+  for (const declaration of input.item.responseDeclarations) {
+    if (
+      scopedResponseIdentifiers !== undefined &&
+      !scopedResponseIdentifiers.has(declaration.identifier)
+    ) {
+      continue;
+    }
+
+    const value = responses.get(declaration.identifier);
+    if (value !== undefined) {
+      validateResponseCardinality(declaration, value, diagnostics);
+    }
+
+    const interactions = interactionsByResponse.get(declaration.identifier);
+    if (interactions === undefined) {
+      validateDeclarationResponse(
+        declaration,
+        undefined,
+        value,
+        input.allowIncompleteResponses,
+        diagnostics,
+      );
+      continue;
+    }
+
+    for (const interaction of interactions) {
+      validateDeclarationResponse(
+        declaration,
+        interaction,
+        value,
+        input.allowIncompleteResponses,
+        diagnostics,
+      );
+    }
+  }
+
+  return {
+    ok: diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+    diagnostics,
+  };
+}
+
+function ingestSubmittedResponses(
+  input: QtiResponseVariablesInput,
+  declaredIdentifiers: ReadonlySet<string>,
+  allowedUndeclaredIdentifiers: ReadonlySet<string>,
+  diagnostics: QtiResponseValidationDiagnostic[],
+): Map<string, QtiValue> {
+  const responses = new Map<string, QtiValue>();
+
+  for (const entry of listNamedResponseInputs(input)) {
+    const identifier = entry.identifier.trim();
+    if (!identifier) {
+      diagnostics.push({
+        code: "response.identifier.required",
+        severity: "error",
+        message: "Response identifiers must be non-empty strings.",
+      });
+      continue;
+    }
+
+    const value = readQtiJsonValue(entry.value);
+    if (value === undefined) {
+      diagnostics.push({
+        code: "response.value.invalid",
+        severity: "error",
+        identifier,
+        message: `Response ${identifier} is not a supported QTI value.`,
+        path: identifier,
+      });
+      continue;
+    }
+
+    if (!declaredIdentifiers.has(identifier)) {
+      if (allowedUndeclaredIdentifiers.has(identifier)) continue;
+      diagnostics.push({
+        code: "response.undeclared",
+        severity: "error",
+        identifier,
+        message: `Response ${identifier} is not declared by the assessment item.`,
+        path: identifier,
+      });
+      continue;
+    }
+
+    responses.set(identifier, value);
+  }
+
+  return responses;
+}
+
+function indexInteractionsByResponse(
+  interactions: readonly QtiInteraction[],
+): Map<string, QtiInteraction[]> {
+  const indexed = new Map<string, QtiInteraction[]>();
+  for (const interaction of interactions) {
+    const identifier = interaction.responseIdentifier;
+    if (!identifier) continue;
+    const bucket = indexed.get(identifier);
+    if (bucket) {
+      bucket.push(interaction);
+    } else {
+      indexed.set(identifier, [interaction]);
+    }
+  }
+  return indexed;
+}
+
+function validateResponseCardinality(
+  declaration: QtiResponseDeclaration,
+  value: QtiValue,
+  diagnostics: QtiResponseValidationDiagnostic[],
+): void {
+  if (value === null) return;
+
+  if (matchesCardinality(declaration.cardinality, value)) return;
+  diagnostics.push({
+    code: "response.cardinality",
+    severity: "error",
+    identifier: declaration.identifier,
+    message: `Response ${declaration.identifier} must match ${declaration.cardinality} cardinality.`,
+    path: declaration.identifier,
+    source: declaration.source,
+  });
+}
+
+function matchesCardinality(cardinality: QtiCardinality, value: QtiValue): boolean {
+  switch (cardinality) {
+    case "single":
+      return !Array.isArray(value) && !isRecordValue(value);
+    case "multiple":
+    case "ordered":
+      return Array.isArray(value);
+    case "record":
+      return isRecordValue(value);
+  }
+  return assertNever(cardinality);
+}
+
+function validateDeclarationResponse(
+  declaration: QtiResponseDeclaration,
+  interaction: QtiInteraction | undefined,
+  value: QtiValue | undefined,
+  allowIncompleteResponses: boolean | undefined,
+  diagnostics: QtiResponseValidationDiagnostic[],
+): void {
+  const policy = responseValidationPolicy(declaration, interaction);
+  if (!policy.checkMinimum && !policy.checkMaximum && !policy.checkMatchMax) return;
+
+  const effectiveValue = value ?? null;
+  const count =
+    interaction?.type === "media" ? mediaPlayCount(effectiveValue) : responseCount(effectiveValue);
+
+  if (policy.checkMinimum && !allowIncompleteResponses) {
+    const minimum = effectiveMinimumRequiredResponses(declaration, interaction);
+    if (count < minimum) {
+      diagnostics.push(
+        attachResponseIdentifier(
+          declaration.identifier,
+          requiredResponseDiagnostic(declaration.identifier, interaction, minimum),
+        ),
+      );
+    }
+  }
+
+  if (policy.checkMaximum && value !== undefined && !isNullResponse(value)) {
+    const maximum = maximumAllowedResponses(interaction);
+    if (maximum !== undefined && count > maximum) {
+      diagnostics.push(
+        attachResponseIdentifier(
+          declaration.identifier,
+          maximumResponseDiagnostic(declaration.identifier, interaction, maximum),
+        ),
+      );
+    }
+  }
+
+  if (policy.checkMatchMax && interaction && value !== undefined && !isNullResponse(value)) {
+    diagnostics.push(
+      ...matchMaxDiagnostics(declaration.identifier, interaction, value).map((diagnostic) =>
+        attachResponseIdentifier(declaration.identifier, diagnostic),
+      ),
+    );
+  }
+}
+
+function effectiveMinimumRequiredResponses(
+  declaration: { readonly correctResponse: QtiValue | null },
+  interaction: QtiInteraction | undefined,
+): number {
+  const minimum = minimumRequiredResponses(interaction);
+  if (declaration.correctResponse === null || hasAuthoredMinimum(interaction)) return minimum;
+  return Math.max(minimum, 1);
+}
+
+function hasAuthoredMinimum(interaction: QtiInteraction | undefined): boolean {
+  if (!interaction) return false;
+  if (interaction.type === "media") return interaction.attributes["min-plays"] !== undefined;
+  return responseLimitAttribute(interaction, "min-choices", "min-associations") !== undefined;
+}
+
+function attachResponseIdentifier(
+  identifier: string,
+  diagnostic: QtiDiagnostic,
+): QtiResponseValidationDiagnostic {
+  if (!isResponseValidationDiagnosticCode(diagnostic.code)) {
+    throw new Error(`Unexpected response validation code: ${diagnostic.code}`);
+  }
+  return { ...diagnostic, identifier, code: diagnostic.code };
+}
+
+function isResponseValidationDiagnosticCode(
+  code: string,
+): code is QtiResponseValidationDiagnosticCode {
+  return (
+    code === "response.required" ||
+    code === "response.maximum" ||
+    code === "response.matchMax" ||
+    code === "response.cardinality" ||
+    code === "response.undeclared" ||
+    code === "response.identifier.required" ||
+    code === "response.value.invalid"
+  );
+}

package/src/scoring-disposition-policy.ts

@@ -0,0 +1,37 @@
+import type { QtiAssessmentItem } from "./types.js";
+import { itemExpectsAutomatedScore } from "./item-scoring-expectation.js";
+
+export type QtiItemSubmissionScoringDisposition =
+  | "scored"
+  | "manual-scoring-required"
+  | "unscored-reference"
+  | "invalid";
+
+const MANUALLY_SCORED_INTERACTION_TYPES = new Set<string>([
+  "custom",
+  "drawing",
+  "extendedText",
+  "portableCustom",
+  "upload",
+]);
+
+/** Interaction types that typically require human review even without response processing. */
+export function itemHasManuallyScoredInteractions(item: QtiAssessmentItem): boolean {
+  return item.interactions.some((interaction) =>
+    MANUALLY_SCORED_INTERACTION_TYPES.has(interaction.type),
+  );
+}
+
+export function itemNeedsScoringFollowUpWhenUnscored(item: QtiAssessmentItem): boolean {
+  return itemExpectsAutomatedScore(item) || itemHasManuallyScoredInteractions(item);
+}
+
+/** Default generic disposition taxonomy shipped by qti3-core for submission materialization. */
+export function classifyQtiItemScoringDisposition(
+  item: QtiAssessmentItem,
+  score: number | null,
+): Exclude<QtiItemSubmissionScoringDisposition, "invalid"> {
+  if (score !== null) return "scored";
+  if (itemNeedsScoringFollowUpWhenUnscored(item)) return "manual-scoring-required";
+  return "unscored-reference";
+}