@longsightgroup/qti3-core 0.3.0 → 0.4.0

package/src/server-scoring.ts

@@ -0,0 +1,244 @@
+import { createItemSession } from "./session.js";
+import { parseQtiXml } from "./parser.js";
+import type {
+  QtiAssessmentItem,
+  QtiAttemptStateV1,
+  QtiAttemptStatus,
+  QtiDiagnostic,
+  QtiPortableCustomStateValue,
+  QtiScoreResult,
+  QtiValue,
+} from "./types.js";
+import { isQtiPortableCustomStateValue, readQtiJsonValue } from "./value-format.js";
+
+export interface QtiServerScoringResponseInput {
+  identifier: string;
+  value: unknown;
+}
+
+export interface QtiServerScoringInput {
+  itemXml: string;
+  /**
+   * Server-trusted response values. This API validates JSON/QTI value shape and declared
+   * identifiers, but it does not run candidate response-validation policy such as required
+   * interactions or min/max response counts.
+   */
+  trustedResponses?: Record<string, unknown> | readonly QtiServerScoringResponseInput[] | undefined;
+  trustedInteractionStates?: Record<string, QtiPortableCustomStateValue> | undefined;
+  status?: QtiAttemptStatus | undefined;
+  allowedUndeclaredResponseIdentifiers?: readonly string[] | undefined;
+}
+
+export interface QtiServerScoringResult {
+  ok: boolean;
+  diagnostics: QtiDiagnostic[];
+  state: QtiAttemptStateV1 | null;
+  responses: Record<string, QtiValue>;
+  outcomes: Record<string, QtiValue>;
+  score: number | null;
+}
+
+export function scoreQtiItemServerSide(input: QtiServerScoringInput): QtiServerScoringResult {
+  let parsed: ReturnType<typeof parseQtiXml>;
+  try {
+    parsed = parseQtiXml(input.itemXml);
+  } catch (error) {
+    return failed([
+      {
+        code: "xml.parse",
+        severity: "error",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    ]);
+  }
+
+  const allowedUndeclaredResponseIdentifiers = new Set(
+    input.allowedUndeclaredResponseIdentifiers ?? [],
+  );
+  const parseDiagnostics = parsed.diagnostics.filter(
+    (diagnostic) =>
+      !isAllowedUndeclaredVariableReference(diagnostic, allowedUndeclaredResponseIdentifiers),
+  );
+  if (!parsed.document || parseDiagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return failed(parseDiagnostics);
+  }
+
+  const diagnostics = [...parseDiagnostics];
+  const session = createItemSession(parsed.document);
+  if (input.status) session.setStatus(input.status);
+
+  const responseIdentifiers = new Set(
+    parsed.document.item.responseDeclarations.map((declaration) => declaration.identifier),
+  );
+
+  for (const response of normalizeResponseInputs(input.trustedResponses)) {
+    const identifier = response.identifier.trim();
+    if (!identifier) {
+      diagnostics.push({
+        code: "serverScoring.response.identifier",
+        severity: "error",
+        message: "Trusted response identifiers must be non-empty strings.",
+      });
+      continue;
+    }
+
+    if (
+      !responseIdentifiers.has(identifier) &&
+      !allowedUndeclaredResponseIdentifiers.has(identifier)
+    ) {
+      diagnostics.push({
+        code: "serverScoring.response.ignored",
+        severity: "warning",
+        message: `Trusted response ${identifier} was ignored because it is not declared by the item.`,
+      });
+      continue;
+    }
+
+    const value = readQtiJsonValue(response.value);
+    if (value === undefined) {
+      diagnostics.push({
+        code: "serverScoring.response.value",
+        severity: "error",
+        message: `Trusted response ${identifier} is not a supported QTI value.`,
+      });
+      continue;
+    }
+    session.respond(identifier, value);
+  }
+
+  for (const [identifier, state] of Object.entries(input.trustedInteractionStates ?? {})) {
+    if (!isQtiPortableCustomStateValue(state)) {
+      diagnostics.push({
+        code: "serverScoring.interactionState.value",
+        severity: "error",
+        message: `Trusted interaction state ${identifier} is not a supported portable custom state value.`,
+      });
+      continue;
+    }
+
+    try {
+      session.setInteractionState(identifier, state);
+    } catch (error) {
+      diagnostics.push({
+        code: "serverScoring.interactionState.identifier",
+        severity: "error",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return failed(diagnostics);
+  }
+
+  let scored: QtiScoreResult;
+  try {
+    scored = session.score();
+  } catch (error) {
+    return failed([
+      ...diagnostics,
+      {
+        code: "serverScoring.score.exception",
+        severity: "error",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    ]);
+  }
+
+  const scoredDiagnostics = [...diagnostics, ...scored.diagnostics];
+  const score = readNumericScore(scored.outcomes.SCORE);
+  const scoredState = stripUndeclaredResponses(scored.state, responseIdentifiers);
+  if (scored.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return failed(scoredDiagnostics, scoredState, scored.outcomes, score);
+  }
+
+  if (shouldRequireNumericScore(parsed.document.item) && score === null) {
+    return failed(
+      [
+        ...scoredDiagnostics,
+        {
+          code: "serverScoring.score.missing",
+          severity: "error",
+          message: "Server-side scoring did not produce a numeric SCORE outcome.",
+        },
+      ],
+      scoredState,
+      scored.outcomes,
+      score,
+    );
+  }
+
+  return {
+    ok: true,
+    diagnostics: scoredDiagnostics,
+    state: scoredState,
+    responses: scoredState.responses,
+    outcomes: scored.outcomes,
+    score,
+  };
+}
+
+function normalizeResponseInputs(
+  responses: QtiServerScoringInput["trustedResponses"],
+): QtiServerScoringResponseInput[] {
+  if (!responses) return [];
+  if (Array.isArray(responses)) return [...responses];
+  return Object.entries(responses).map(([identifier, value]) => ({ identifier, value }));
+}
+
+function shouldRequireNumericScore(item: QtiAssessmentItem): boolean {
+  return (
+    Boolean(item.responseProcessing) ||
+    item.outcomeDeclarations.some((declaration) => declaration.identifier === "SCORE")
+  );
+}
+
+function readNumericScore(value: QtiValue | undefined): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const score = Number(value.trim());
+    return Number.isFinite(score) ? score : null;
+  }
+  return null;
+}
+
+function isAllowedUndeclaredVariableReference(
+  diagnostic: QtiDiagnostic,
+  allowedUndeclaredResponseIdentifiers: Set<string>,
+): boolean {
+  if (diagnostic.code !== "processing.variable.reference") return false;
+  const identifier = diagnostic.message.match(
+    /^Processing expression references missing variable (.+)\.$/,
+  )?.[1];
+  return Boolean(identifier && allowedUndeclaredResponseIdentifiers.has(identifier));
+}
+
+function failed(
+  diagnostics: QtiDiagnostic[],
+  state: QtiAttemptStateV1 | null = null,
+  outcomes: Record<string, QtiValue> = {},
+  score: number | null = null,
+): QtiServerScoringResult {
+  return {
+    ok: false,
+    diagnostics,
+    state,
+    responses: state?.responses ?? {},
+    outcomes,
+    score,
+  };
+}
+
+function stripUndeclaredResponses(
+  state: QtiAttemptStateV1,
+  declaredResponseIdentifiers: Set<string>,
+): QtiAttemptStateV1 {
+  return {
+    ...state,
+    responses: Object.fromEntries(
+      Object.entries(state.responses).filter(([identifier]) =>
+        declaredResponseIdentifiers.has(identifier),
+      ),
+    ),
+  };
+}

package/src/session.ts

@@ -17,7 +17,13 @@ import type {
   QtiValue,
   QtiVariableDeclaration,
 } from "./types.js";
-import { qtiScalarToString, qtiValueToString, qtiValueToStringList } from "./value-format.js";
+import {
+  isQtiPortableCustomStateValue,
+  isQtiValue,
+  qtiScalarToString,
+  qtiValueToString,
+  qtiValueToStringList,
+} from "./value-format.js";
 
 export interface QtiCustomOperatorContext {
   definition?: string | undefined;
@@ -1995,33 +2001,13 @@ function isRecordValue(value: QtiValue): value is QtiRecordValue {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function isQtiValue(value: unknown): value is QtiValue {
-  if (value === null) return true;
-  if (isQtiScalarValue(value)) return true;
-  if (Array.isArray(value)) return value.every(isQtiScalarValue);
-  return isQtiValueRecord(value);
-}
-
-function isQtiScalarValue(value: unknown): value is QtiScalarValue {
-  return (
-    typeof value === "string" ||
-    typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value))
-  );
-}
-
 function isQtiValueRecord(value: unknown): value is Record<string, QtiValue> {
   if (!isRecord(value)) return false;
   return Object.values(value).every(isQtiValue);
 }
 
 function isPortableCustomState(value: unknown): value is QtiPortableCustomStateValue {
-  if (value === null) return true;
-  if (typeof value === "string" || typeof value === "boolean") return true;
-  if (typeof value === "number") return Number.isFinite(value);
-  if (Array.isArray(value)) return value.every(isPortableCustomState);
-  if (isRecord(value)) return Object.values(value).every(isPortableCustomState);
-  return false;
+  return isQtiPortableCustomStateValue(value);
 }
 
 function isPortableCustomStateObject(

package/src/value-format.ts

@@ -1,4 +1,54 @@
-import type { QtiScalarValue, QtiValue } from "./types.js";
+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);
@@ -37,3 +87,17 @@ export function unknownToDisplayString(value: unknown): string {
   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

@@ -10,6 +10,8 @@ export interface XmlNode {
   content: Array<string | XmlNode>;
   text: string;
   source: XmlSourceLocation;
+  endSource?: XmlSourceLocation | undefined;
+  sourceRange: XmlSourceRange;
   parent?: XmlNode;
 }
 
@@ -20,60 +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,
-        prefix: event.prefix,
-        uri: event.uri,
-        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 };
@@ -99,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;