@longsightgroup/qti3-core 0.2.1 → 0.4.0

package/src/types.ts

@@ -416,7 +416,10 @@ export interface QtiAssessmentItem {
   title?: string | undefined;
   language?: string | undefined;
   adaptive: boolean;
+  timeDependent?: boolean | undefined;
+  attributes: Record<string, string>;
   prompt?: string | undefined;
+  itemBodySource?: QtiSourceLocation | undefined;
   responseDeclarations: QtiResponseDeclaration[];
   outcomeDeclarations: QtiOutcomeDeclaration[];
   templateDeclarations: QtiTemplateDeclaration[];

package/src/validation.ts

@@ -21,6 +21,7 @@ import type {
   QtiValidationResult,
 } from "./types.js";
 import { validateQtiDataSsmlMetadata } from "./tts.js";
+import { qtiValueToStringList } from "./value-format.js";
 
 const BUILT_IN_COMPLETION_STATUS = "completionStatus";
 
@@ -29,6 +30,8 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
   const item = document.item;
 
   requireIdentifier("qti-assessment-item", item.identifier, diagnostics, item.source);
+  validateAssessmentItemRoot(item, diagnostics);
+  validateItemBody(item, diagnostics);
   validateDeclarationIdentifiers(item, diagnostics);
   validateOutcomeLookupTables(item, diagnostics);
   validateInteractions(item, diagnostics);
@@ -36,6 +39,7 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
   validateCatalogInfo(item, diagnostics);
   validateStylesheets(item, diagnostics);
   diagnostics.push(...validateQtiDataSsmlMetadata(item));
+  validateResponseProcessingTemplate(item, diagnostics);
   validateProcessingReferences(item, diagnostics);
 
   return {
@@ -44,6 +48,152 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
   };
 }
 
+function validateResponseProcessingTemplate(
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  const template = item.responseProcessing?.template;
+  if (!template) return;
+  const templateKind = responseProcessingTemplateKind(template);
+  if (templateKind) {
+    validateBuiltInResponseProcessingTemplate(item, templateKind, diagnostics);
+    return;
+  }
+  diagnostics.push({
+    code: "processing.template.unsupported",
+    severity: "error",
+    message: `qti-response-processing template ${template} is not currently supported.`,
+    path: item.source?.path,
+    source: item.source,
+  });
+}
+
+function responseProcessingTemplateKind(
+  template: string,
+): "matchCorrect" | "mapResponse" | "mapResponsePoint" | undefined {
+  const path = template.split(/[?#]/, 1)[0] ?? "";
+  const name = path.slice(path.lastIndexOf("/") + 1).replace(/\.xml$/i, "");
+  if (name === "match_correct") return "matchCorrect";
+  if (name === "map_response") return "mapResponse";
+  if (name === "map_response_point") return "mapResponsePoint";
+  return undefined;
+}
+
+function validateAssessmentItemRoot(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
+  if (!item.attributes.title?.trim()) {
+    diagnostics.push({
+      code: "assessmentItem.title.required",
+      severity: "error",
+      message: "qti-assessment-item requires a non-empty title attribute.",
+      path: item.source?.path,
+      source: item.source,
+    });
+  }
+  const timeDependent = item.attributes["time-dependent"];
+  if (timeDependent === undefined || timeDependent.trim() === "") {
+    diagnostics.push({
+      code: "assessmentItem.timeDependent.required",
+      severity: "error",
+      message: "qti-assessment-item requires a time-dependent attribute.",
+      path: item.source?.path,
+      source: item.source,
+    });
+  } else if (!isXmlBoolean(timeDependent)) {
+    diagnostics.push({
+      code: "assessmentItem.timeDependent.boolean",
+      severity: "error",
+      message: `qti-assessment-item time-dependent must be an XML boolean, found ${timeDependent}.`,
+      path: item.source?.path,
+      source: item.source,
+    });
+  }
+}
+
+function validateBuiltInResponseProcessingTemplate(
+  item: QtiAssessmentItem,
+  templateKind: "matchCorrect" | "mapResponse" | "mapResponsePoint",
+  diagnostics: QtiDiagnostic[],
+): void {
+  const response = item.responseDeclarations.find(
+    (declaration) => declaration.identifier === "RESPONSE",
+  );
+  const score = item.outcomeDeclarations.find((declaration) => declaration.identifier === "SCORE");
+  if (!response) {
+    diagnostics.push({
+      code: "processing.template.responseIdentifier",
+      severity: "error",
+      message:
+        "Built-in response-processing templates require a response declaration named RESPONSE.",
+      path: item.source?.path,
+      source: item.source,
+    });
+  }
+  if (!score) {
+    diagnostics.push({
+      code: "processing.template.scoreIdentifier",
+      severity: "error",
+      message: "Built-in response-processing templates require an outcome declaration named SCORE.",
+      path: item.source?.path,
+      source: item.source,
+    });
+  } else if (score.cardinality !== "single" || score.baseType !== "float") {
+    diagnostics.push({
+      code: "processing.template.scoreDeclaration",
+      severity: "error",
+      message:
+        "Built-in response-processing templates require SCORE to be single cardinality with base-type float.",
+      path: score.source?.path,
+      source: score.source,
+    });
+  }
+  const responseInteractions = item.interactions.filter(
+    (interaction) => interaction.responseIdentifier === "RESPONSE",
+  );
+  if (responseInteractions.length !== 1 || item.interactions.length !== 1) {
+    diagnostics.push({
+      code: "processing.template.singleInteraction",
+      severity: "error",
+      message:
+        "Built-in response-processing templates require a single interaction bound to RESPONSE.",
+      path: item.source?.path,
+      source: item.source,
+    });
+  }
+  if (templateKind === "mapResponse" && response && !response.mapping) {
+    diagnostics.push({
+      code: "processing.template.mapping",
+      severity: "error",
+      message: "The map_response template requires RESPONSE to define qti-mapping.",
+      path: response.source?.path,
+      source: response.source,
+    });
+  }
+  if (templateKind === "mapResponsePoint" && response && !response.areaMapping) {
+    diagnostics.push({
+      code: "processing.template.areaMapping",
+      severity: "error",
+      message: "The map_response_point template requires RESPONSE to define qti-area-mapping.",
+      path: response.source?.path,
+      source: response.source,
+    });
+  }
+}
+
+function isXmlBoolean(value: string): boolean {
+  return value === "true" || value === "false" || value === "1" || value === "0";
+}
+
+function validateItemBody(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[]): void {
+  if (item.itemBodySource) return;
+  diagnostics.push({
+    code: "itemBody.required",
+    severity: "error",
+    message: "qti-assessment-item requires a qti-item-body.",
+    path: item.source?.path,
+    source: item.source,
+  });
+}
+
 function requireIdentifier(
   elementName: string,
   identifier: string | undefined,
@@ -1599,8 +1749,7 @@ function validateCorrectResponseReferences(
 }
 
 function responseValues(value: QtiResponseDeclaration["correctResponse"]): string[] {
-  if (Array.isArray(value)) return value.map(String);
-  return [String(value)];
+  return qtiValueToStringList(value);
 }
 
 function invalidCorrectResponseReference(

package/src/value-format.ts

@@ -0,0 +1,103 @@
+import type { QtiPortableCustomStateValue, QtiScalarValue, QtiValue } from "./types.js";
+
+export function isQtiValue(value: unknown): value is QtiValue {
+  return readQtiJsonValue(value) !== undefined;
+}
+
+export function readQtiJsonValue(value: unknown): QtiValue | undefined {
+  if (value === null || isQtiScalarValue(value)) return value;
+  if (Array.isArray(value)) return value.every(isQtiScalarValue) ? value : undefined;
+  if (!isPlainRecord(value)) return undefined;
+
+  const record: Record<string, QtiValue> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const converted = readQtiJsonValue(entry);
+    if (converted === undefined) return undefined;
+    record[key] = converted;
+  }
+  return record;
+}
+
+export function isQtiPortableCustomStateValue(
+  value: unknown,
+): value is QtiPortableCustomStateValue {
+  return readQtiPortableCustomStateValue(value) !== undefined;
+}
+
+export function readQtiPortableCustomStateValue(
+  value: unknown,
+): QtiPortableCustomStateValue | undefined {
+  if (value === null) return value;
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (Array.isArray(value)) {
+    const values: QtiPortableCustomStateValue[] = [];
+    for (const entry of value) {
+      const converted = readQtiPortableCustomStateValue(entry);
+      if (converted === undefined) return undefined;
+      values.push(converted);
+    }
+    return values;
+  }
+  if (!isPlainRecord(value)) return undefined;
+
+  const record: Record<string, QtiPortableCustomStateValue> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const converted = readQtiPortableCustomStateValue(entry);
+    if (converted === undefined) return undefined;
+    record[key] = converted;
+  }
+  return record;
+}
+
+export function qtiScalarToString(value: QtiScalarValue): string {
+  return String(value);
+}
+
+export function qtiValueToString(value: QtiValue): string {
+  if (value === null) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return qtiScalarToString(value);
+  }
+  if (Array.isArray(value)) return value.map(qtiScalarToString).join(" ");
+  return JSON.stringify(value);
+}
+
+export function qtiValueToStringList(value: QtiValue): string[] {
+  if (value === null) return [""];
+  if (Array.isArray(value)) return value.map(qtiScalarToString);
+  if (typeof value === "object") return [JSON.stringify(value)];
+  return [qtiScalarToString(value)];
+}
+
+export function qtiValueToIdentifierList(value: QtiValue): string[] {
+  if (value === null) return [];
+  if (Array.isArray(value)) return value.map(qtiScalarToString);
+  if (typeof value === "object") return [JSON.stringify(value)];
+  return [qtiScalarToString(value)];
+}
+
+export function unknownToDisplayString(value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "bigint" || typeof value === "symbol") return String(value);
+  if (Array.isArray(value)) return value.map(unknownToDisplayString).join(", ");
+  if (typeof value === "object") return JSON.stringify(value);
+  return JSON.stringify(value);
+}
+
+function isQtiScalarValue(value: unknown): value is QtiScalarValue {
+  return (
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  );
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/xml.ts

@@ -3,11 +3,15 @@ import { StaxXmlParserSync, XmlEventType } from "stax-xml";
 export interface XmlNode {
   name: string;
   localName: string;
+  prefix?: string | undefined;
+  uri?: string | undefined;
   attributes: Record<string, string>;
   children: XmlNode[];
   content: Array<string | XmlNode>;
   text: string;
   source: XmlSourceLocation;
+  endSource?: XmlSourceLocation | undefined;
+  sourceRange: XmlSourceRange;
   parent?: XmlNode;
 }
 
@@ -18,58 +22,102 @@ export interface XmlSourceLocation {
   path: string;
 }
 
+export interface XmlSourceRange {
+  /** String offset of `<` for this element's start tag in the source XML string. */
+  startOffset: number;
+  /** String offset of `>` closing the start tag (or `/>` for self-closing tags). */
+  startTagEndOffset: number;
+  /** String offset one past the element's closing `>` (or self-closing `/>`). */
+  endOffset?: number | undefined;
+}
+
 export function parseXmlTree(xml: string): { root: XmlNode | undefined; errors: Error[] } {
   const parser = new StaxXmlParserSync(xml, {
     autoDecodeEntities: true,
   });
+  const tagTokens = scanXmlTagTokens(xml);
   const stack: XmlNode[] = [];
   const errors: Error[] = [];
   let root: XmlNode | undefined;
-  let searchOffset = 0;
+  let tagTokenIndex = 0;
 
-  for (const event of parser) {
-    if (event.type === XmlEventType.ERROR) {
-      errors.push(event.error);
-      continue;
-    }
+  try {
+    for (const event of parser) {
+      if (event.type === XmlEventType.ERROR) {
+        errors.push(event.error);
+        continue;
+      }
+
+      if (event.type === XmlEventType.START_ELEMENT) {
+        const parent = stack.at(-1);
+        const path = nodePath(parent, event.localName ?? event.name);
+        const sourceRange: XmlSourceRange = { startOffset: -1, startTagEndOffset: -1 };
+        const token = tagTokens[tagTokenIndex];
+        if (token?.kind === "start" && token.name === event.name) {
+          tagTokenIndex += 1;
+          sourceRange.startOffset = token.startOffset;
+          sourceRange.startTagEndOffset = token.startTagEndOffset;
+          if (token.endOffset !== undefined) {
+            sourceRange.endOffset = token.endOffset;
+          }
+        } else {
+          errors.push(new Error(`XML source range alignment failed for <${event.name}>.`));
+        }
+        const node: XmlNode = {
+          name: event.name,
+          localName: event.localName ?? event.name,
+          prefix: event.prefix,
+          uri: event.uri,
+          attributes: event.attributes,
+          children: [],
+          content: [],
+          text: "",
+          source: sourceLocation(xml, sourceRange.startOffset, path),
+          sourceRange,
+        };
 
-    if (event.type === XmlEventType.START_ELEMENT) {
-      const parent = stack.at(-1);
-      const offset = findStartElementOffset(xml, event.name, searchOffset);
-      searchOffset = offset >= 0 ? offset + 1 : searchOffset;
-      const node: XmlNode = {
-        name: event.name,
-        localName: event.localName ?? event.name,
-        attributes: event.attributes,
-        children: [],
-        content: [],
-        text: "",
-        source: sourceLocation(xml, offset, nodePath(parent, event.localName ?? event.name)),
-      };
-
-      if (parent) {
-        node.parent = parent;
-        parent.children.push(node);
-        parent.content.push(node);
-      } else {
-        root = node;
+        if (parent) {
+          node.parent = parent;
+          parent.children.push(node);
+          parent.content.push(node);
+        } else {
+          root = node;
+        }
+        stack.push(node);
+        continue;
       }
-      stack.push(node);
-      continue;
-    }
 
-    if (event.type === XmlEventType.END_ELEMENT) {
-      stack.pop();
-      continue;
-    }
+      if (event.type === XmlEventType.END_ELEMENT) {
+        const node = stack.pop();
+        if (node) {
+          if (node.sourceRange.endOffset === undefined) {
+            const token = tagTokens[tagTokenIndex];
+            if (token?.kind === "end" && token.name === event.name) {
+              tagTokenIndex += 1;
+              node.sourceRange.endOffset = token.endOffset;
+              node.endSource = sourceLocation(xml, token.startOffset, node.source.path);
+            } else {
+              errors.push(new Error(`XML source range alignment failed for </${event.name}>.`));
+            }
+          }
+        }
+        continue;
+      }
 
-    if (event.type === XmlEventType.CHARACTERS || event.type === XmlEventType.CDATA) {
-      const node = stack.at(-1);
-      if (node) {
-        node.text += event.value;
-        node.content.push(event.value);
+      if (event.type === XmlEventType.CHARACTERS || event.type === XmlEventType.CDATA) {
+        const node = stack.at(-1);
+        if (node) {
+          node.text += event.value;
+          node.content.push(event.value);
+        }
       }
     }
+  } catch (error) {
+    errors.push(error instanceof Error ? error : new Error(String(error)));
+  }
+
+  for (const node of [...stack].reverse()) {
+    errors.push(new Error(`Unexpected end of document. Missing closing tag for <${node.name}>.`));
   }
 
   return { root, errors };
@@ -95,28 +143,152 @@ export function textContent(node: XmlNode): string {
   return parts.join(" ").replace(/\s+/g, " ").trim();
 }
 
-function findStartElementOffset(xml: string, name: string, from: number): number {
-  let offset = from;
+interface XmlTagToken {
+  kind: "start" | "end";
+  name: string;
+  startOffset: number;
+  startTagEndOffset: number;
+  endOffset?: number | undefined;
+  selfClosing: boolean;
+}
+
+function scanXmlTagTokens(xml: string): XmlTagToken[] {
+  const tokens: XmlTagToken[] = [];
+  let offset = 0;
+
   while (offset < xml.length) {
-    const start = xml.indexOf("<", offset);
-    if (start === -1) return -1;
-    const next = xml.charAt(start + 1);
-    if (next === "/" || next === "!" || next === "?") {
-      offset = start + 1;
+    const startOffset = xml.indexOf("<", offset);
+    if (startOffset === -1 || startOffset + 1 >= xml.length) return tokens;
+
+    if (xml.startsWith("<!--", startOffset)) {
+      offset = skipPastSequence(xml, "-->", startOffset + 4);
+      continue;
+    }
+
+    if (xml.startsWith("<![CDATA[", startOffset)) {
+      offset = skipPastSequence(xml, "]]>", startOffset + 9);
+      continue;
+    }
+
+    const next = xml.charAt(startOffset + 1);
+    if (next === "?") {
+      offset = skipPastSequence(xml, "?>", startOffset + 2);
+      continue;
+    }
+
+    if (next === "!") {
+      const declarationEndOffset = findMarkupDeclarationEndOffset(xml, startOffset + 2);
+      offset = declarationEndOffset >= 0 ? declarationEndOffset + 1 : xml.length;
+      continue;
+    }
+
+    if (next === "/") {
+      const tagEndOffset = findTagEndOffset(xml, startOffset + 2);
+      if (tagEndOffset < 0) return tokens;
+      const name = readTagName(xml, startOffset + 2, tagEndOffset);
+      if (name) {
+        tokens.push({
+          kind: "end",
+          name,
+          startOffset,
+          startTagEndOffset: tagEndOffset,
+          endOffset: tagEndOffset + 1,
+          selfClosing: false,
+        });
+      }
+      offset = tagEndOffset + 1;
+      continue;
+    }
+
+    const tagEndOffset = findTagEndOffset(xml, startOffset + 1);
+    if (tagEndOffset < 0) return tokens;
+    const name = readTagName(xml, startOffset + 1, tagEndOffset);
+    if (name) {
+      const selfClosing = isSelfClosingStartTag(xml, tagEndOffset);
+      tokens.push({
+        kind: "start",
+        name,
+        startOffset,
+        startTagEndOffset: tagEndOffset,
+        endOffset: selfClosing ? tagEndOffset + 1 : undefined,
+        selfClosing,
+      });
+    }
+    offset = tagEndOffset + 1;
+  }
+
+  return tokens;
+}
+
+function skipPastSequence(xml: string, sequence: string, from: number): number {
+  const endOffset = xml.indexOf(sequence, from);
+  return endOffset >= 0 ? endOffset + sequence.length : xml.length;
+}
+
+function findMarkupDeclarationEndOffset(xml: string, from: number): number {
+  let quote: string | null = null;
+  let internalSubsetDepth = 0;
+  for (let index = from; index < xml.length; index += 1) {
+    const char = xml.charAt(index);
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === "[") {
+      internalSubsetDepth += 1;
       continue;
     }
-    const afterName = start + 1 + name.length;
-    if (
-      xml.slice(start + 1, afterName) === name &&
-      (afterName >= xml.length || /[\s/>]/.test(xml.charAt(afterName)))
-    ) {
-      return start;
+    if (char === "]" && internalSubsetDepth > 0) {
+      internalSubsetDepth -= 1;
+      continue;
     }
-    offset = start + 1;
+    if (char === ">" && internalSubsetDepth === 0) return index;
   }
   return -1;
 }
 
+function readTagName(xml: string, from: number, to: number): string {
+  let start = from;
+  while (start < to && /\s/.test(xml.charAt(start))) start += 1;
+  let end = start;
+  while (end < to) {
+    const char = xml.charAt(end);
+    if (/\s/.test(char) || char === "/" || char === ">") break;
+    end += 1;
+  }
+  return xml.slice(start, end);
+}
+
+function findTagEndOffset(xml: string, from: number): number {
+  let quote: string | null = null;
+  for (let index = from; index < xml.length; index += 1) {
+    const char = xml.charAt(index);
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === ">") return index;
+  }
+  return -1;
+}
+
+function isSelfClosingStartTag(xml: string, tagEndOffset: number): boolean {
+  for (let index = tagEndOffset - 1; index >= 0; index -= 1) {
+    const char = xml.charAt(index);
+    if (/\s/.test(char)) continue;
+    return char === "/";
+  }
+  return false;
+}
+
 function sourceLocation(xml: string, offset: number, path: string): XmlSourceLocation {
   if (offset < 0) return { line: 1, column: 1, offset: 0, path };
   let line = 1;