app-utils.js

(function(global){
  'use strict';

  const isString = (value) => typeof value === 'string' || value instanceof String;
  const trimToEmpty = (value) => (isString(value) ? String(value).trim() : '');
  const collapseWhitespace = (value) => trimToEmpty(value).replace(/\s+/g, ' ');
  const hasText = (value) => trimToEmpty(value).length > 0;

  const formatQuestionPrompt = (question) => {
    if (!question || typeof question !== 'object') return '';
    const id = trimToEmpty(question.id);
    const text = trimToEmpty(question.text);
    if (id && text) return `(${id}) ${text}`;
    if (id) return `(${id})`;
    return text;
  };

  const getGroupKey = (question) => {
    const id = trimToEmpty(question && question.id);
    if (id.length < 3) return '';
    return id.slice(0, 3).toUpperCase();
  };

  const buildExamRun = (pool, options = {}) => {
    const {
      required = 35,
      filterFigures = false,
      hasFigure = () => false,
      rng = Math.random,
    } = options;

    if (!Array.isArray(pool) || pool.length === 0) {
      throw new Error('Question pool is invalid or empty.');
    }

    const groupOrder = [];
    const groupBuckets = new Map();

    pool.forEach((question) => {
      const group = getGroupKey(question);
      if (!group) return;
      if (!groupBuckets.has(group)) {
        groupBuckets.set(group, []);
        groupOrder.push(group);
      }
      groupBuckets.get(group).push(question);
    });

    if (groupOrder.length === 0) {
      throw new Error('Question pool is missing group identifiers.');
    }

    if (required > groupOrder.length) {
      throw new Error('Question pool does not contain enough groups to build an exam.');
    }

    const shuffledGroups = [...groupOrder];
    for (let i = shuffledGroups.length - 1; i > 0; i -= 1) {
      const pick = Math.floor(rng() * (i + 1));
      [shuffledGroups[i], shuffledGroups[pick]] = [shuffledGroups[pick], shuffledGroups[i]];
    }

    const selections = [];
    for (let i = 0; i < required; i += 1) {
      const group = shuffledGroups[i];
      const candidates = groupBuckets.get(group) || [];
      const viable = filterFigures ? candidates.filter((q) => !hasFigure(q)) : candidates;
      if (viable.length === 0) {
        throw new Error(filterFigures ? 'Not enough non-figure questions to build a full exam.' : `Question group ${group} is empty.`);
      }
      const pickIndex = Math.floor(rng() * viable.length);
      selections.push(viable[pickIndex]);
    }

    return selections;
  };

  const parsePlainTextPool = (rawText, options = {}) => {
    if (!isString(rawText)) {
      throw new Error('Question pool source must be a string.');
    }

    const {
      expectedChoices = ['A', 'B', 'C', 'D'],
      allowDuplicateIds = false,
      normalizeWhitespace = true,
      onQuestion = null,
    } = options;

    const normalizeText = (value) => {
      if (!normalizeWhitespace) return trimToEmpty(value);
      return collapseWhitespace(value);
    };

    const lines = rawText.replace(/\r\n?/g, '\n').split('\n');
    const questions = [];
    const seenIds = new Set();

    const isChoiceLine = (line) => /^[A-D]\.\s/.test(line);
    const isHeaderLine = (line) => /^[A-Za-z][A-Za-z0-9]{2,5}\s*\([A-D]\)/.test(line);

    for (let index = 0; index < lines.length; index += 1) {
      const headerCandidate = trimToEmpty(lines[index]);
      const headerMatch = headerCandidate.match(/^([A-Za-z][A-Za-z0-9]{2,5})\s*\(([A-D])\)\s*(?:\[(.*?)\])?$/);
      if (!headerMatch) continue;

      const id = headerMatch[1].toUpperCase();
      const correct = headerMatch[2].toUpperCase();
      const reference = trimToEmpty(headerMatch[3]);

      index += 1;
      const questionParts = [];

      while (index < lines.length) {
        const rawLine = lines[index];
        const trimmed = trimToEmpty(rawLine);
        if (!trimmed) {
          index += 1;
          continue;
        }
        if (trimmed === '~~' || isChoiceLine(trimmed) || isHeaderLine(trimmed)) break;
        questionParts.push(rawLine);
        index += 1;
      }

      const questionText = normalizeText(questionParts.join(' '));
      const choices = {};
      let currentLetter = '';

      while (index < lines.length) {
        const rawLine = lines[index];
        const trimmed = trimToEmpty(rawLine);
        if (!trimmed) {
          index += 1;
          continue;
        }
        if (trimmed === '~~') {
          index += 1;
          break;
        }
        if (isHeaderLine(trimmed)) break;

        const choiceMatch = trimmed.match(/^([A-D])\.\s*(.*)$/);
        if (choiceMatch) {
          currentLetter = choiceMatch[1].toUpperCase();
          choices[currentLetter] = normalizeText(choiceMatch[2]);
          index += 1;
          continue;
        }

        if (currentLetter) {
          const existing = choices[currentLetter] || '';
          choices[currentLetter] = normalizeText(`${existing} ${rawLine}`);
          index += 1;
          continue;
        }

        questionParts.push(rawLine);
        index += 1;
      }

      const hasAllChoices = expectedChoices.every((letter) => hasText(choices[letter]));
      if (!hasAllChoices) {
        continue;
      }

      if (!allowDuplicateIds) {
        if (seenIds.has(id)) continue;
        seenIds.add(id);
      }

      const question = {
        id,
        text: questionText,
        choices,
        correct,
      };

      if (reference) question.reference = reference;
      questions.push(question);

      if (typeof onQuestion === 'function') {
        onQuestion(question);
      }
    }

    return questions;
  };

  const escapeHTML = (value) => String(value || '')
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;');

  const api = {
    formatQuestionPrompt,
    buildExamRun,
    parsePlainTextPool,
    escapeHTML,
  };

  global.HAMLEARN_UTILS = api;
  if (typeof module !== 'undefined' && module.exports) {
    module.exports = api;
  }
})(typeof window !== 'undefined' ? window : globalThis);