syntax.js

class TraversalSyntaxError extends Error {
  constructor(message, offset, length = 1) {
    super(message);
    this.name = "TraversalSyntaxError";
    this.offset = offset;
    this.length = length;
  }
}

/** @typedef {{start: number, end: number}} SourceSpan */
/** @typedef {{kind: "pointer", id: string, span: SourceSpan, wrapperSpan?: SourceSpan}} PointerSyntax */
/** @typedef {{kind: "group", items: TraversalItem[], span: SourceSpan}} GroupSyntax */
/** @typedef {PointerSyntax | GroupSyntax} TraversalItem */
/** @typedef {{kind: "traversal", items: TraversalItem[], span: SourceSpan, source: string}} TraversalSyntax */

function span(start, end) {
  return { start, end };
}

function diagnostic(code, category, severity, message, sourceSpan) {
  return { code, category, severity, message, span: sourceSpan };
}

function isBarePointer(pointer) {
  return typeof pointer === "string" &&
    pointer.length > 0 &&
    !/[\s()[\]:"\\]/.test(pointer);
}

function serializePointer(pointer) {
  if (typeof pointer !== "string" || pointer.length === 0) {
    throw new TypeError("A PGX pointer must be a non-empty string.");
  }
  return isBarePointer(pointer) ? pointer : JSON.stringify(pointer);
}

const preferredPointerPattern = /^[A-Z]+[0-9]+$/;
const toleratedPointerPattern = /^[A-Z]+[0-9]+(?:[.-][0-9]+)+$/;
const recommendedPointerLength = 32;

function pointerStyleDiagnostic(pointer, sourceSpan) {
  if (pointer.length <= recommendedPointerLength && preferredPointerPattern.test(pointer)) {
    return undefined;
  }
  if (pointer.length <= recommendedPointerLength && toleratedPointerPattern.test(pointer)) {
    return diagnostic(
      "pointer-style-variant",
      "pointer-style",
      "hint",
      "This pointer is lawful, but a compact uppercase-letter prefix followed by one integer, such as A1 or CONTEXT6, is easier to recognize and parse.",
      sourceSpan
    );
  }
  return diagnostic(
    "pointer-style-discouraged",
    "pointer-style",
    "warning",
    "This pointer is lawful and will continue to work, but its shape may be title-like, escape-prone, or unnecessarily long. Prefer uppercase letters followed by digits, such as A1, AB11, or CONTEXT6.",
    sourceSpan
  );
}

function tokenizeTraversal(source, baseOffset = 0) {
  const tokens = [];
  let offset = 0;

  while (offset < source.length) {
    const character = source[offset];
    if (/\s/.test(character)) {
      offset += 1;
      continue;
    }

    if (character === '"') {
      let end = offset + 1;
      let escaped = false;
      while (end < source.length) {
        const current = source[end];
        if (!escaped && current === '"') {
          end += 1;
          break;
        }
        if (!escaped && current === "\\") {
          escaped = true;
        } else {
          escaped = false;
        }
        end += 1;
      }
      if (end > source.length || source[end - 1] !== '"') {
        throw new TraversalSyntaxError(
          "Unterminated quoted PGX pointer.",
          baseOffset + offset,
          Math.max(1, source.length - offset)
        );
      }
      const raw = source.slice(offset, end);
      let value;
      try {
        value = JSON.parse(raw);
      } catch {
        throw new TraversalSyntaxError(
          "Invalid escape in quoted PGX pointer.",
          baseOffset + offset,
          raw.length
        );
      }
      if (!value) {
        throw new TraversalSyntaxError(
          "A PGX pointer must not be empty.",
          baseOffset + offset,
          raw.length
        );
      }
      tokens.push({
        type: "pointer",
        value,
        quoted: true,
        span: span(baseOffset + offset, baseOffset + end)
      });
      offset = end;
      continue;
    }

    const structuralTokens = {
      "(": "leftParen",
      ")": "rightParen",
      "[": "leftBracket",
      "]": "rightBracket",
      ":": "colon"
    };
    const type = structuralTokens[character];
    if (type) {
      tokens.push({
        type,
        value: character,
        span: span(baseOffset + offset, baseOffset + offset + 1)
      });
      offset += 1;
      continue;
    }

    const pointer = source.slice(offset).match(/^[^\s()[\]:"\\]+/);
    if (pointer) {
      tokens.push({
        type: "pointer",
        value: pointer[0],
        quoted: false,
        span: span(baseOffset + offset, baseOffset + offset + pointer[0].length)
      });
      offset += pointer[0].length;
      continue;
    }

    const unexpected = source.slice(offset).match(/^\S+/)?.[0] ?? character;
    throw new TraversalSyntaxError(
      `Unexpected text “${unexpected}”; expected a pointer or traversal delimiter.`,
      baseOffset + offset,
      unexpected.length
    );
  }

  return tokens;
}

/**
 * Parse an ordered PGX traversal while retaining exact pointer and grouping spans.
 * @param {string} source
 * @param {{baseOffset?: number}} options
 * @returns {TraversalSyntax}
 */
function parseTraversal(source, options = {}) {
  const baseOffset = options.baseOffset ?? 0;
  const tokens = tokenizeTraversal(source, baseOffset);
  if (tokens.length === 0) {
    throw new TraversalSyntaxError("Select at least one PGX pointer.", baseOffset, 0);
  }

  let cursor = 0;
  const peek = () => tokens[cursor];
  const consume = () => tokens[cursor++];

  function unclosedMessage(stopType) {
    return stopType === "rightParen"
      ? "Unclosed parenthesis in traversal selection."
      : "Unclosed square bracket in traversal selection.";
  }

  function parseSequence(stopType, openingToken) {
    const items = [];
    let expectsItem = true;

    while (cursor < tokens.length) {
      const token = peek();
      if (token.type === stopType) {
        if (items.length === 0) {
          throw new TraversalSyntaxError(
            "Empty traversal groups are not allowed.",
            token.span.start
          );
        }
        if (expectsItem) {
          throw new TraversalSyntaxError(
            "A traversal cannot end with a colon.",
            token.span.start
          );
        }
        consume();
        return { items, closingToken: token };
      }

      if (token.type === "rightParen" || token.type === "rightBracket") {
        const delimiter = token.type === "rightParen" ? ")" : "]";
        throw new TraversalSyntaxError(
          `Unexpected closing delimiter “${delimiter}”.`,
          token.span.start
        );
      }

      if (token.type === "colon") {
        if (expectsItem) {
          throw new TraversalSyntaxError(
            "A colon must appear between two traversal elements.",
            token.span.start
          );
        }
        consume();
        expectsItem = true;
        continue;
      }

      if (!expectsItem && token.type === "leftBracket") {
        throw new TraversalSyntaxError(
          "Square brackets can only wrap the complete traversal.",
          token.span.start
        );
      }

      items.push(parseItem());
      expectsItem = false;
    }

    if (stopType) {
      throw new TraversalSyntaxError(
        unclosedMessage(stopType),
        openingToken.span.start
      );
    }
    if (expectsItem && items.length > 0) {
      const finalToken = tokens.at(-1);
      throw new TraversalSyntaxError(
        "A traversal cannot end with a colon.",
        finalToken.span.start
      );
    }
    return { items };
  }

  function parseItem() {
    const token = consume();
    if (token.type === "pointer") {
      return { kind: "pointer", id: token.value, span: token.span };
    }

    if (token.type === "leftParen") {
      const parsed = parseSequence("rightParen", token);
      const itemSpan = span(token.span.start, parsed.closingToken.span.end);
      if (parsed.items.length === 1) {
        return { ...parsed.items[0], wrapperSpan: itemSpan };
      }
      return { kind: "group", items: parsed.items, span: itemSpan };
    }

    if (token.type === "leftBracket") {
      throw new TraversalSyntaxError(
        "Square brackets can only wrap the complete traversal.",
        token.span.start
      );
    }

    throw new TraversalSyntaxError(
      "Expected a PGX pointer or parenthesized group.",
      token.span.start
    );
  }

  let items;
  let traversalSpan;
  if (peek().type === "leftBracket") {
    const opening = consume();
    const parsed = parseSequence("rightBracket", opening);
    items = parsed.items;
    traversalSpan = span(opening.span.start, parsed.closingToken.span.end);
    if (cursor < tokens.length) {
      throw new TraversalSyntaxError(
        "Nothing may follow the traversal’s closing square bracket.",
        peek().span.start
      );
    }
  } else {
    const parsed = parseSequence();
    items = parsed.items;
    traversalSpan = span(tokens[0].span.start, tokens.at(-1).span.end);
  }

  return { kind: "traversal", items, span: traversalSpan, source };
}

function parseTraversalResult(source, options = {}) {
  try {
    return { ok: true, value: parseTraversal(source, options), diagnostics: [] };
  } catch (error) {
    if (!(error instanceof TraversalSyntaxError)) {
      throw error;
    }
    return {
      ok: false,
      diagnostics: [
        diagnostic(
          "traversal-syntax",
          "lawful-syntax",
          "error",
          error.message,
          span(error.offset, error.offset + Math.max(error.length, 1))
        )
      ]
    };
  }
}

function renderSequence(items, renderPointer) {
  return items.map((item) => renderItem(item, renderPointer)).join(":");
}

function renderItem(item, renderPointer) {
  if (item.kind === "pointer") {
    return `(${renderPointer(item)})`;
  }
  return `(${renderSequence(item.items, renderPointer)})`;
}

function renderTraversalAst(
  traversal,
  renderPointer = (pointer) => serializePointer(pointer.id)
) {
  return `[${renderSequence(traversal.items, renderPointer)}]`;
}

function validateTraversalPointers(traversal, validatePointer) {
  if (typeof validatePointer !== "function") {
    return;
  }
  walkTraversal(traversal, (pointer) => {
    if (!validatePointer(pointer.id)) {
      throw new TraversalSyntaxError(
        `Unknown PGX pointer “${pointer.id}”.`,
        pointer.span.start,
        Math.max(1, pointer.span.end - pointer.span.start)
      );
    }
  });
}

function canonicalizeTraversalSelection(source, options = {}) {
  const traversal = parseTraversal(source);
  validateTraversalPointers(traversal, options.validatePointer);
  return renderTraversalAst(traversal);
}

function canonicalizeTraversalBatch(source, options = {}) {
  const segments = source.split(/(\r\n|\n|\r)/);
  if (segments.length === 1) {
    return canonicalizeTraversalSelection(source, options);
  }

  let absoluteOffset = 0;
  let convertedLines = 0;
  let firstError;
  const rendered = [];

  for (let index = 0; index < segments.length; index += 2) {
    const line = segments[index];
    const lineEnding = segments[index + 1] ?? "";
    const leadingWhitespace = line.match(/^\s*/)?.[0] ?? "";
    const content = line.trim();

    if (!content || content.startsWith("#")) {
      rendered.push(line, lineEnding);
    } else {
      try {
        rendered.push(
          `${leadingWhitespace}${canonicalizeTraversalSelection(content, options)}`,
          lineEnding
        );
        convertedLines += 1;
      } catch (error) {
        if (!firstError && error instanceof TraversalSyntaxError) {
          firstError = new TraversalSyntaxError(
            `Line ${index / 2 + 1}: ${error.message}`,
            absoluteOffset + leadingWhitespace.length + error.offset,
            error.length
          );
        }
        rendered.push(line, lineEnding);
      }
    }
    absoluteOffset += line.length + lineEnding.length;
  }

  if (!firstError && convertedLines > 0) {
    return rendered.join("");
  }
  if (firstError) {
    try {
      return canonicalizeTraversalSelection(source, options);
    } catch {
      throw firstError;
    }
  }
  throw new TraversalSyntaxError("Select at least one line containing PGX pointers.", 0, 0);
}

function walkTraversal(traversal, visitor) {
  function walkItems(items, path) {
    items.forEach((item, ordinal) => {
      const itemPath = [...path, ordinal];
      if (item.kind === "pointer") {
        visitor(item, itemPath);
      } else {
        walkItems(item.items, itemPath);
      }
    });
  }
  walkItems(traversal.items, []);
}

function trimmedField(raw, absoluteStart) {
  const leading = raw.length - raw.trimStart().length;
  const value = raw.trim();
  return {
    value,
    span: span(absoluteStart + leading, absoluteStart + leading + value.length)
  };
}

function parsePgxLine(line, lineNumber, lineStart, sourceId) {
  const diagnostics = [];
  const trimmed = line.trim();
  if (!trimmed || trimmed.startsWith("#")) {
    return { diagnostics };
  }
  const sigilIndex = line.toLowerCase().indexOf("pgx:");
  if (sigilIndex < 0) {
    return { diagnostics };
  }

  if (!line.startsWith("pgx:")) {
    diagnostics.push(
      diagnostic(
        "pgx-sigil-position",
        "lawful-syntax",
        "error",
        "A lawful PGX node must start literally with pgx: at the beginning of the line.",
        span(lineStart + sigilIndex, lineStart + sigilIndex + 4)
      )
    );
    return { diagnostics };
  }

  const opening = line.slice(4).match(/^\s*\|\|/);
  if (!opening) {
    diagnostics.push(
      diagnostic(
        "pgx-opening-delimiter",
        "lawful-syntax",
        "error",
        "Expected opening field delimiter || after pgx:.",
        span(lineStart + 4, lineStart + Math.max(5, line.length))
      )
    );
    return { diagnostics };
  }

  const contentStart = 4 + opening[0].length;
  const hasClosing = /\|\|\s*$/.test(line.slice(contentStart));
  if (!hasClosing) {
    diagnostics.push(
      diagnostic(
        "pgx-closing-delimiter",
        "lawful-syntax",
        "error",
        "Every PGX field must end with ||; this node is missing its final delimiter.",
        span(lineStart + Math.max(0, line.length - 1), lineStart + line.length)
      )
    );
    return { diagnostics };
  }

  const fields = [];
  let fieldStart = contentStart;
  let delimiter = line.indexOf("||", fieldStart);
  while (delimiter >= 0) {
    fields.push(trimmedField(line.slice(fieldStart, delimiter), lineStart + fieldStart));
    fieldStart = delimiter + 2;
    delimiter = line.indexOf("||", fieldStart);
  }

  const [pointerField, titleField, descriptionField, ...dataFieldEntries] = fields;
  if (!pointerField?.value) {
    diagnostics.push(
      diagnostic(
        "schema1-pointer",
        "schema-profile-1",
        "warning",
        "Schema Profile 1 expects the first delimited field to be the pointer.",
        span(lineStart, lineStart + line.length)
      )
    );
    return { diagnostics };
  }

  let descriptionTraversal;
  const description = descriptionField?.value ?? "";
  if (description.trimStart().startsWith("[")) {
    const parsed = parseTraversalResult(description, {
      baseOffset: descriptionField.span.start
    });
    if (parsed.ok) {
      descriptionTraversal = parsed.value;
    } else {
      diagnostics.push(
        ...parsed.diagnostics.map((entry) => ({
          ...entry,
          code: "invalid-description-traversal",
          category: "schema-profile-1",
          message: `Malformed traversal description: ${entry.message}`
        }))
      );
    }
  }

  const pointer = pointerField.value;
  const styleDiagnostic = pointerStyleDiagnostic(pointer, pointerField.span);
  if (styleDiagnostic) {
    diagnostics.push(styleDiagnostic);
  }
  return {
    diagnostics,
    node: {
      kind: "node",
      identity: `${sourceId}:${pointerField.span.start}`,
      provenance: "document",
      sourceId,
      sigil: "pgx",
      pointer,
      title: titleField?.value ?? "",
      description,
      dataFields: dataFieldEntries.map((field) => field.value),
      fields,
      lineNumber,
      span: span(lineStart, lineStart + line.length),
      pointerSpan: pointerField.span,
      titleSpan: titleField?.span,
      descriptionSpan: descriptionField?.span,
      descriptionTraversal
    }
  };
}

function parsePgxDocument(source, sourceId = "document") {
  const nodes = [];
  const diagnostics = [];
  const lineStarts = [];
  const linePattern = /.*(?:\r\n|\n|\r|$)/g;
  let lineNumber = 0;
  let match;

  while ((match = linePattern.exec(source)) && match[0] !== "") {
    const raw = match[0];
    const line = raw.replace(/(?:\r\n|\n|\r)$/, "");
    const lineStart = match.index;
    lineStarts.push(lineStart);
    const parsed = parsePgxLine(line, lineNumber, lineStart, sourceId);
    diagnostics.push(...parsed.diagnostics);
    if (parsed.node) {
      nodes.push(parsed.node);
    }
    lineNumber += 1;
  }

  if (source.length === 0) {
    lineStarts.push(0);
  }
  return { source, sourceId, nodes, diagnostics, lineStarts };
}

function profileNode(entry, index, diagnostics) {
  const pointer = typeof entry.pointer === "string" ? entry.pointer.trim() : "";
  if (pointer) {
    const styleDiagnostic = pointerStyleDiagnostic(pointer);
    if (styleDiagnostic) {
      diagnostics.push(styleDiagnostic);
    }
  }
  let descriptionTraversal;
  const description = typeof entry.description === "string" ? entry.description : "";
  if (description.trimStart().startsWith("[")) {
    const parsed = parseTraversalResult(description);
    if (parsed.ok) {
      descriptionTraversal = parsed.value;
    } else {
      diagnostics.push(
        ...parsed.diagnostics.map((item) => ({
          ...item,
          code: "invalid-profile-traversal",
          category: "schema-profile-1",
          message: `${pointer || `Profile node ${index}`} has a malformed traversal: ${item.message}`
        }))
      );
    }
  }

  return {
    kind: "node",
    identity: `profile:${index}:${pointer}`,
    provenance: "profile",
    sourceId: "profile",
    sigil: entry.sigil ?? "pgx",
    pointer,
    title: typeof entry.title === "string" ? entry.title : "",
    description,
    dataFields: Object.entries(entry)
      .filter(([key]) => /^data\d+$/.test(key))
      .sort(([left], [right]) => Number(left.slice(4)) - Number(right.slice(4)))
      .map(([, value]) => String(value)),
    lineNumber: index,
    span: undefined,
    pointerSpan: undefined,
    descriptionTraversal,
    raw: entry
  };
}

function parseProfile(profile = {}) {
  const diagnostics = [];
  const entries = Array.isArray(profile.nodes) ? profile.nodes : [];
  const nodes = entries.map((entry, index) => profileNode(entry, index, diagnostics));
  return {
    schemaProfile: profile.schemaProfile,
    nodes,
    diagnostics
  };
}

module.exports = {
  TraversalSyntaxError,
  canonicalizeTraversalBatch,
  canonicalizeTraversalSelection,
  diagnostic,
  parsePgxDocument,
  parseProfile,
  parseTraversal,
  parseTraversalResult,
  renderTraversalAst,
  serializePointer,
  span,
  walkTraversal
};