interlinearXmlParser.ts

import { X2jOptions, XMLParser } from 'fast-xml-parser';

/** Character range in source text (Index, Length). */
export interface StringRange {
  /** Start index of the range in the source text (0-based). */
  Index: number;
  /** Number of characters in the range. */
  Length: number;
}

/** Data on the interlinearization of a single lexeme. */
export interface LexemeData {
  /** ID of the lexeme (e.g. from Lexicon; XML attribute Id). */
  LexemeId: string;
  /** ID of the sense/gloss used for this lexeme (XML attribute GlossId). */
  SenseId: string;
}

/** Data on the interlinearization of a cluster. */
export interface ClusterData {
  /** Character range this cluster occupies in the verse text. */
  TextRange: StringRange;
  /** Lexemes in this cluster, in order. */
  Lexemes: LexemeData[];
  /** Slash-joined LexemeIds for this cluster (e.g. "Word:a/Word:b"). */
  LexemesId: string;
  /** Unique cluster id: LexemesId plus TextRange (e.g. "Word:a/Word:b/21-3"). */
  Id: string;
  /** Excluded flag. See [pt9-xml.md](./pt9-xml.md) for details. */
  Excluded: boolean;
}

/** Data on punctuation change. */
export interface PunctuationData {
  /** Character range this punctuation occupies in the verse text. */
  TextRange: StringRange;
  /** Punctuation text before the change (or empty). */
  BeforeText: string;
  /** Punctuation text after the change (or empty). */
  AfterText: string;
}

/** Interlinear data for a single verse. */
export interface VerseData {
  /** Hash of verse text when approved; empty string if not approved. */
  Hash: string;
  /** Lexeme clusters in this verse. */
  Clusters: ClusterData[];
  /** Punctuation changes in this verse. */
  Punctuations: PunctuationData[];
}

/** Root interlinear data: book + verses. */
export interface InterlinearData {
  /** Source text / project name (e.g. from InterlinearData ScrTextName attribute). */
  ScrTextName: string;
  /** Language code or name for the glosses. */
  GlossLanguage: string;
  /** Book id (e.g. "RUT", "MAT"). */
  BookId: string;
  /**
   * Verse data keyed by verse reference (e.g. "RUT 3:1"). Exactly one entry per reference; the
   * parser rejects XML that contains duplicate verse references.
   */
  Verses: Record<string, VerseData>;
}

/** Range: Index and Length attributes. */
interface ParsedRange {
  /** Start index in source text (FXP attribute Index). */
  ['@_Index']: string;
  /** Length of range (FXP attribute Length). */
  ['@_Length']: string;
}

/** Lexeme: Id (required), optional GlossId. */
interface ParsedLexeme {
  /** Lexeme id (FXP attribute Id). */
  ['@_Id']: string;
  /** Sense/gloss id (FXP attribute GlossId). */
  ['@_GlossId']?: string;
}

/** Cluster: optional Range, optional Lexeme[], optional Excluded. */
interface ParsedCluster {
  /** Range element (Index, Length). */
  Range?: ParsedRange;
  /** Lexeme elements in this cluster. */
  Lexeme?: ParsedLexeme[];
  /** Excluded flag (optional). See [pt9-xml.md](pt9-xml.md) for details. */
  Excluded?: string;
}

/** Punctuation: optional Range, BeforeText, AfterText. */
interface ParsedPunctuation {
  /** Range element for this punctuation. */
  Range?: ParsedRange;
  /** Text before change (tag value). */
  BeforeText?: string;
  /** Text after change (tag value). */
  AfterText?: string;
}

/** VerseData: optional Hash, Cluster[], Punctuation[]. */
interface ParsedVerseData {
  /** Approval hash (FXP attribute Hash). */
  ['@_Hash']?: string;
  /** Cluster elements in this verse. */
  Cluster?: ParsedCluster[];
  /** Punctuation elements in this verse. */
  Punctuation?: ParsedPunctuation[];
}

/** Single entry in Verses: verse key (string), VerseData. */
interface ParsedVersesItem {
  /** Verse reference key (e.g. "RUT 3:1"). */
  string?: string;
  /** Verse data for this key. */
  VerseData?: ParsedVerseData;
}

/** Root element: ScrTextName, GlossLanguage, BookId, Verses (with item[]). */
interface ParsedInterlinearDataRoot {
  /** Source text name (FXP attribute ScrTextName). */
  ['@_ScrTextName']?: string;
  /** Gloss language (FXP attribute GlossLanguage). */
  ['@_GlossLanguage']?: string;
  /** Book id (FXP attribute BookId). */
  ['@_BookId']?: string;
  /** Verses container; item array holds key/value pairs. */
  Verses?: { item?: ParsedVersesItem[] };
}

/** Root document: InterlinearData. */
interface ParsedInterlinearXml {
  /** Root InterlinearData element. */
  InterlinearData?: ParsedInterlinearDataRoot;
}

/**
 * Maps a parsed Cluster's Lexeme array to {@link LexemeData} array.
 *
 * @param clusterElement - Parsed Cluster from fast-xml-parser (may have Lexeme array or none).
 * @returns Array of LexemeData with LexemeId (from Id) and SenseId (from GlossId, or '').
 * @throws {SyntaxError} If any Lexeme element is missing the required Id attribute.
 */
function extractLexemesFromCluster(clusterElement: ParsedCluster): LexemeData[] {
  const elements = clusterElement.Lexeme ?? [];

  return elements.map((el) => {
    const lexemeId = el['@_Id'];
    if (!lexemeId) {
      throw new SyntaxError('Invalid XML: Lexeme missing required Id attribute');
    }
    return { LexemeId: lexemeId, SenseId: el['@_GlossId'] ?? '' };
  });
}

/**
 * Parses a string to a non-negative integer, returning `undefined` for empty or non-integer values.
 * Used to validate XML attribute strings before converting them to numeric ranges.
 *
 * @param raw - The string to parse (e.g. an XML attribute value). `undefined` is accepted because
 *   fast-xml-parser may omit attributes at runtime despite the declared type.
 * @returns The parsed non-negative integer, or `undefined` if the input is absent, empty, or
 *   non-integer.
 */
const parseStrictNumber = (raw: string | undefined): number | undefined => {
  if (raw === undefined || raw.trim() === '') return undefined;
  if (!/^\d+$/.test(raw.trim())) return undefined;
  return Number.parseInt(raw, 10);
};

/**
 * Maps a parsed VerseData's Punctuation array to {@link PunctuationData} array.
 *
 * Uses a **lenient** parsing strategy: entries without a valid `Range` (or with missing /
 * non-integer `Index`/`Length`) are silently filtered out rather than throwing. Punctuation data is
 * non-critical to the interlinear display; clusters are validated strictly in
 * {@link extractClustersFromVerse} because they are required for alignment rendering.
 *
 * @param verseDataElement - Parsed VerseData from fast-xml-parser (may have Punctuation array or
 *   none).
 * @returns Array of PunctuationData (TextRange from Range Index/Length, BeforeText, AfterText).
 *   Entries without a valid Range element are skipped.
 */
function extractPunctuationsFromVerse(verseDataElement: ParsedVerseData): PunctuationData[] {
  const elements = verseDataElement.Punctuation ?? [];

  return elements.flatMap((el) => {
    const rangeElement = el.Range;
    if (!rangeElement) return [];
    const index = parseStrictNumber(rangeElement['@_Index']);
    const length = parseStrictNumber(rangeElement['@_Length']);
    if (index === undefined || length === undefined) return [];
    return [
      {
        TextRange: { Index: index, Length: length },
        BeforeText: el.BeforeText ?? '',
        AfterText: el.AfterText ?? '',
      },
    ];
  });
}

/**
 * Maps a parsed VerseData's Cluster array to {@link ClusterData} array.
 *
 * @param verseDataElement - Parsed VerseData from fast-xml-parser (may have Cluster array or none).
 * @returns Array of ClusterData: TextRange from Cluster's Range, Lexemes from Lexeme children,
 *   LexemesId (slash-joined), Id (LexemesId/Index-Length or Index-Length when no lexemes).
 * @throws {SyntaxError} If a Cluster is missing its Range element, Range is missing Index or
 *   Length, or Range Index/Length are not non-negative integers.
 */
function extractClustersFromVerse(verseDataElement: ParsedVerseData): ClusterData[] {
  const clusterElements = verseDataElement.Cluster ?? [];

  return clusterElements.map((el) => {
    const rangeElement = el.Range;
    if (!rangeElement) {
      throw new SyntaxError('Invalid XML: Cluster missing required Range element');
    }

    if (rangeElement['@_Index'] === undefined || rangeElement['@_Length'] === undefined) {
      throw new SyntaxError('Invalid XML: Range missing Index or Length attribute');
    }

    const index = parseStrictNumber(rangeElement['@_Index']);
    const length = parseStrictNumber(rangeElement['@_Length']);
    if (index === undefined || length === undefined) {
      throw new SyntaxError(
        'Invalid XML: Range has invalid Index/Length attributes (must be non-negative integers)',
      );
    }

    const textRange: StringRange = { Index: index, Length: length };
    const lexemes = extractLexemesFromCluster(el);

    // Join with "/"; lexeme IDs may contain "/", so do not split LexemesId elsewhere.
    const lexemesId = lexemes.map((l) => l.LexemeId).join('/');
    /** Cluster Id: LexemesId/Index-Length when lexemes present; Index-Length when none. */
    const id = lexemesId ? `${lexemesId}/${index}-${length}` : `${index}-${length}`;
    const excluded = el.Excluded === 'true';

    return {
      TextRange: textRange,
      Lexemes: lexemes,
      LexemesId: lexemesId,
      Id: id,
      Excluded: excluded,
    };
  });
}

/**
 * Parses interlinear XML strings into {@link InterlinearData} using fast-xml-parser.
 *
 * Input is a raw XML string (caller is responsible for obtaining it, e.g. from file or network).
 * Output matches the types in `interlinearizer`; no extra conversion is done. Expects the
 * interlinear XML schema described in [pt9-xml.md](pt9-xml.md).
 *
 * Each instance holds a configured `XMLParser`; create one parser and reuse it across multiple
 * `parse()` calls rather than constructing a new instance per file.
 */
export class InterlinearXmlParser {
  /** Shared XMLParser instance, pre-configured in the constructor and reused across `parse()` calls. */
  private readonly parser: XMLParser;

  /**
   * Creates a parser configured for interlinear XML: attribute prefix `@_`, and array paths for
   * Verses items, Cluster, Punctuation, and Lexeme.
   */
  constructor() {
    const arrayPaths = new Set([
      'InterlinearData.Verses.item',
      'InterlinearData.Verses.item.VerseData.Cluster',
      'InterlinearData.Verses.item.VerseData.Punctuation',
      'InterlinearData.Verses.item.VerseData.Cluster.Lexeme',
    ]);

    const options: Partial<X2jOptions> = {
      ignoreAttributes: false,
      attributeNamePrefix: '@_',
      ignoreDeclaration: true,
      ignorePiTags: true,
      trimValues: false,
      parseTagValue: false,
      parseAttributeValue: false,
      isArray: (_tagName, jPath) => arrayPaths.has(`${jPath}`),
    };
    this.parser = new XMLParser(options);
  }

  /**
   * Parses an interlinear XML string into {@link InterlinearData}.
   *
   * @param xml - Raw XML string (e.g. file contents). Must be valid interlinear XML with
   *   InterlinearData root, GlossLanguage and BookId attributes, and Verses containing item
   *   entries.
   * @returns Parsed interlinear data: ScrTextName, GlossLanguage, BookId, and Verses (record of
   *   verse key to {@link VerseData} with Hash, Clusters, Punctuations).
   * @throws {SyntaxError} If the `InterlinearData` root element is absent.
   * @throws {SyntaxError} If `GlossLanguage` or `BookId` attributes are missing or empty.
   * @throws {SyntaxError} If the `Verses` element is absent.
   * @throws {SyntaxError} If a `Cluster` is missing its `Range` element, `Range` is missing
   *   `Index`/`Length`, or `Index`/`Length` are not non-negative integers.
   * @throws {SyntaxError} If a `Lexeme` element is missing its required `Id` attribute.
   * @throws {SyntaxError} If the same verse reference appears in more than one `item`.
   */
  parse(xml: string): InterlinearData {
    const parsed: ParsedInterlinearXml = this.parser.parse(xml);
    const root = parsed.InterlinearData;
    if (!root) {
      throw new SyntaxError('Invalid XML: Missing InterlinearData root element');
    }

    const scrTextName = root['@_ScrTextName'] ?? '';
    const glossLanguage = root['@_GlossLanguage'] ?? '';
    const bookId = root['@_BookId'] ?? '';
    if (!glossLanguage || !bookId) {
      throw new SyntaxError('Invalid XML: Missing required attributes GlossLanguage or BookId');
    }

    const versesElement = root.Verses;
    if (!versesElement) {
      throw new SyntaxError('Invalid XML: Missing Verses element');
    }

    const items = versesElement.item ?? [];

    const seen = new Set<string>();
    const verses = items.reduce<Record<string, VerseData>>((acc, item) => {
      const verseKey = item.string;
      if (!verseKey) return acc;

      if (seen.has(verseKey)) {
        throw new SyntaxError(
          `Invalid XML: Duplicate verse reference "${verseKey}". At most one VerseData per reference is allowed.`,
        );
      }
      seen.add(verseKey);

      const verseDataElement = item.VerseData;
      if (!verseDataElement) {
        acc[verseKey] = { Hash: '', Clusters: [], Punctuations: [] };
        return acc;
      }

      acc[verseKey] = {
        Hash: verseDataElement['@_Hash'] ?? '',
        Clusters: extractClustersFromVerse(verseDataElement),
        Punctuations: extractPunctuationsFromVerse(verseDataElement),
      };
      return acc;
    }, {});

    return {
      ScrTextName: scrTextName,
      GlossLanguage: glossLanguage,
      BookId: bookId,
      Verses: verses,
    };
  }
}