@blamejs/exceptd-skills 0.18.8 → 0.18.11

package/lib/xml-tokenizer.js

@@ -110,6 +110,82 @@ function parseAttrs(rawAttrs) {
   return out;
 }
 
+/**
+ * Emit the character-data of a raw-text leaf element span `[start, end)`.
+ *
+ * CDATA sections inside the span are emitted verbatim (onCData if present,
+ * else onText) exactly like the main loop's CDATA fast-path; all other bytes
+ * — including a stray unescaped '<' or inline HTML — are entity-decoded and
+ * emitted via onText. Keeping the CDATA contract here means a `<![CDATA[...]]>`
+ * title still surfaces only its inner text, not the literal markers.
+ */
+function emitRawText(xml, start, end, H) {
+  let p = start;
+  while (p < end) {
+    const c = xml.indexOf("<![CDATA[", p);
+    if (c === -1 || c >= end) {
+      const chunk = xml.slice(p, end);
+      if (chunk.length && H.onText) H.onText(decodeEntities(chunk));
+      return;
+    }
+    if (c > p) {
+      const chunk = xml.slice(p, c);
+      if (chunk.length && H.onText) H.onText(decodeEntities(chunk));
+    }
+    const cend = xml.indexOf("]]>", c + 9);
+    // findRawTextEnd already guaranteed a terminated CDATA before the close
+    // tag, so cend is within range; guard anyway.
+    const inner = cend === -1 || cend > end ? xml.slice(c + 9, end) : xml.slice(c + 9, cend);
+    if (H.onCData) H.onCData(inner);
+    else if (H.onText) H.onText(inner);
+    p = cend === -1 || cend > end ? end : cend + 3;
+  }
+}
+
+/**
+ * Locate the matching close tag of a raw-text leaf element.
+ *
+ * Scans `xml` from `start` (the byte after the leaf open tag's `>`) for the
+ * first close tag `</...name>` whose local-name (namespace prefix stripped)
+ * equals `name`. CDATA sections are skipped verbatim so a `</title>` that
+ * legitimately appears inside `<![CDATA[ ... ]]>` is treated as literal text,
+ * not as the element's terminator.
+ *
+ * Returns { contentEnd, next } on success — `contentEnd` is the index of the
+ * close tag's leading `<`, `next` is the index just past its `>`. Returns null
+ * when no matching close tag exists before EOF (genuinely truncated input).
+ */
+function findRawTextEnd(xml, start, name) {
+  const len = xml.length;
+  let j = start;
+  while (j < len) {
+    const lt = xml.indexOf("<", j);
+    if (lt === -1) return null;
+    // Step over a CDATA section so its contents (which may contain "</name>"
+    // literally) cannot satisfy the close-tag match.
+    if (xml.startsWith("<![CDATA[", lt)) {
+      const cend = xml.indexOf("]]>", lt + 9);
+      if (cend === -1) return null; // unterminated CDATA → truncated
+      j = cend + 3;
+      continue;
+    }
+    if (xml[lt + 1] === "/") {
+      const gt = xml.indexOf(">", lt + 2);
+      if (gt === -1) return null;
+      const closeName = localName(xml.slice(lt + 2, gt).trim());
+      if (closeName === name) {
+        return { contentEnd: lt, next: gt + 1 };
+      }
+      j = gt + 1;
+      continue;
+    }
+    // Any other '<' (stray literal '<', or an inner open tag like <b>) is part
+    // of the leaf's character data — advance past it without classifying.
+    j = lt + 1;
+  }
+  return null;
+}
+
 /**
  * Streaming tokenizer. Calls handlers in document order. Returns no
  * value — accumulation is the caller's responsibility.
@@ -122,6 +198,17 @@ function parseAttrs(rawAttrs) {
  *   onComment(text)
  *   onPI(name, content)  processing instructions (<?xml-stylesheet?>)
  *   onError(message, position)
+ *
+ * Options (second-position fields on the handlers object):
+ *   rawTextElements   Set<string> of leaf-element local-names whose content
+ *                     is #PCDATA — once such an element opens, every byte up
+ *                     to the matching `</name>` close tag is treated as
+ *                     character data (entities decoded, then onText), exactly
+ *                     like the CDATA fast-path. This makes leaf fields tolerant
+ *                     of stray unescaped '<' (e.g. "affects versions < 5.0"),
+ *                     which real RSS/Atom routinely emits, instead of letting a
+ *                     recoverable lexical glitch silently drop the whole field.
+ *                     Structural parsing stays strict for container elements.
  */
 function tokenize(xml, handlers) {
   const H = handlers || {};
@@ -129,6 +216,7 @@ function tokenize(xml, handlers) {
     if (H.onError) H.onError("input must be a string", 0);
     return;
   }
+  const rawTextElements = H.rawTextElements instanceof Set ? H.rawTextElements : null;
   const len = xml.length;
   let i = 0;
   // Open-tag stack — surfaces EOF-with-unclosed-elements as an error
@@ -229,9 +317,33 @@ function tokenize(xml, handlers) {
       if (H.onTagClose) H.onTagClose(name);
     } else {
       const attrs = parseAttrs(rawAttrs);
-      if (!selfClose) openStack.push(name);
       if (H.onTagOpen) H.onTagOpen(name, attrs, selfClose);
-      if (selfClose && H.onTagClose) H.onTagClose(name);
+      if (selfClose) {
+        if (H.onTagClose) H.onTagClose(name);
+      } else if (rawTextElements && rawTextElements.has(name)) {
+        // Raw-text leaf element (title/summary/description/...). Its content
+        // is #PCDATA: scan to the matching `</name>` and treat the whole span
+        // as character data — only the matching close tag terminates it. Any
+        // inner '<...>' (a stray unescaped '<', or inline HTML like <b>) is
+        // preserved as text and normalized later by stripHtml(), instead of
+        // being misclassified as markup and silently dropping the field.
+        const span = findRawTextEnd(xml, close + 1, name);
+        if (span === null) {
+          // Genuinely truncated: the leaf never closes before EOF. Surface
+          // the loud-error contract just like the structural path would, then
+          // flush the residual as text and stop.
+          if (H.onError) H.onError("unterminated element at EOF: " + name, len);
+          const tail = xml.slice(close + 1);
+          if (tail.length && H.onText) H.onText(decodeEntities(tail));
+          return;
+        }
+        emitRawText(xml, close + 1, span.contentEnd, H);
+        if (H.onTagClose) H.onTagClose(name);
+        i = span.next;
+        continue;
+      } else {
+        openStack.push(name);
+      }
     }
     i = close + 1;
   }
@@ -240,15 +352,36 @@ function tokenize(xml, handlers) {
   }
 }
 
+// Leaf-element local-names whose content is character-data (#PCDATA). When
+// one of these opens, the tokenizer runs in raw-text mode until the matching
+// close tag, so a stray unescaped '<' inside the field (e.g. "affects
+// versions < 5.0") is preserved as text instead of being misclassified as
+// markup and silently dropping the whole field.
+const LEAF_FIELDS = new Set([
+  "title", "link", "pubDate", "published", "updated",
+  "description", "content", "summary",
+]);
+
+// rel-rank for Atom <link> sibling selection. RFC 4287: a <link> with no rel
+// defaults to rel="alternate", the canonical article URL. A non-alternate rel
+// (self / replies / edit / enclosure) should never clobber an alternate.
+function relRank(rel) {
+  if (rel == null || rel === "" || String(rel).toLowerCase() === "alternate") return 2;
+  return 1;
+}
+
 /**
- * Parse an RSS / Atom feed into a flat array of items. Returns:
- *   [{ title, link, published, body, raw_attrs: {...} }, ...]
+ * Parse an RSS / Atom feed, always collecting parse errors.
+ *
+ * Returns { items, errors } where errors is an array of
+ * { message, position } records. This is the channel a caller cannot forget
+ * to opt into — parseFeed() below is a thin back-compat wrapper.
  *
- * Empty array on parse failure. `errors` (out-of-band) captured via
- * the optional `errors` array — callers wanting observability pass it.
+ *   items: [{ title, link, published, body }, ...]
  */
-function parseFeed(xml, errors = null) {
+function parseFeedDetailed(xml) {
   const items = [];
+  const errors = [];
   // Stack of "in-progress item" contexts. RSS uses <item>; Atom uses
   // <entry>; both nest title / link / pubDate / published / updated /
   // description / content / summary.
@@ -266,25 +399,34 @@ function parseFeed(xml, errors = null) {
   let current = null;       // active item context
   let activeField = null;   // active field local-name
   let buffer = "";          // accumulator for current field text
-  let linkHref = null;      // captured from <link href="..."/> attribute
+  let linkRank = 0;         // rel-rank of the best <link> captured so far
 
   tokenize(xml, {
+    rawTextElements: LEAF_FIELDS,
     onTagOpen(name, attrs, selfClosing) {
       if (ITEM_LOCALS.has(name)) {
         current = { title: "", link: "", published: "", body: "" };
+        linkRank = 0;
         return;
       }
       if (!current) return;
       if (FIELD_MAP[name]) {
         activeField = FIELD_MAP[name];
         buffer = "";
-        // Atom <link href="..."/> — capture the href attribute as the
-        // link value. RSS <link>...</link> uses element text instead.
-        if (name === "link" && attrs && attrs.href) linkHref = attrs.href;
-        if (selfClosing && name === "link" && linkHref) {
-          current.link = linkHref;
-          linkHref = null;
-          activeField = null;
+        // Atom <link href="..."/> — rel-aware selection. Only let an
+        // alternate / rel-absent link upgrade the captured value, and never
+        // let a non-alternate rel (self/replies/edit) clobber an alternate
+        // already in hand. First-alternate-wins, independent of document
+        // order.
+        if (name === "link" && attrs && attrs.href) {
+          const r = relRank(attrs.rel);
+          if (r > linkRank) {
+            current.link = attrs.href;
+            linkRank = r;
+          }
+          // The link value has been resolved from the attribute — there is
+          // no element-text close to wait for.
+          if (selfClosing) activeField = null;
         }
       }
     },
@@ -294,28 +436,31 @@ function parseFeed(xml, errors = null) {
         current = null;
         activeField = null;
         buffer = "";
+        linkRank = 0;
         return;
       }
       if (!current) return;
       if (FIELD_MAP[name] && activeField === FIELD_MAP[name]) {
         const value = buffer.trim();
-        // Element-text link overrides the attribute capture when
-        // both are present.
-        if (name === "link" && value) {
-          current.link = value;
-        } else if (name === "link" && !value && linkHref) {
-          current.link = linkHref;
+        // RSS <link>...</link> — element text is authoritative (rank 2),
+        // unconditional. An empty element-text link falls back to whatever
+        // attribute capture onTagOpen already recorded.
+        if (name === "link") {
+          if (value) {
+            current.link = value;
+            linkRank = 2;
+          }
         } else if (activeField === "body" || activeField === "title") {
           // Strip HTML tags from title + description / content / summary.
           // Many feeds embed inline HTML (<b>, <em>, <a>) in titles for
           // emphasis; the operational consumer wants plain text. CDATA
           // content reaches here verbatim, so this also strips HTML
-          // that was wrapped in CDATA to dodge entity-encoding.
+          // that was wrapped in CDATA to dodge entity-encoding. A stray
+          // unescaped '<' that survived raw-text mode collapses here too.
           current[activeField] = stripHtml(value);
         } else {
           current[activeField] = value;
         }
-        linkHref = null;
         activeField = null;
         buffer = "";
       }
@@ -327,10 +472,27 @@ function parseFeed(xml, errors = null) {
       if (activeField) buffer += text;
     },
     onError(msg, pos) {
-      if (errors) errors.push({ message: msg, position: pos });
+      errors.push({ message: msg, position: pos });
     }
   });
 
+  return { items, errors };
+}
+
+/**
+ * Parse an RSS / Atom feed into a flat array of items. Returns:
+ *   [{ title, link, published, body }, ...]
+ *
+ * Empty array on parse failure. Errors are ALWAYS collected internally; the
+ * optional `errors` array is filled for callers that pass one (back-compat).
+ * Prefer parseFeedDetailed(xml) for new callers — it returns the errors
+ * channel unconditionally so it cannot be silently dropped.
+ */
+function parseFeed(xml, errors = null) {
+  const { items, errors: collected } = parseFeedDetailed(xml);
+  if (Array.isArray(errors)) {
+    for (const e of collected) errors.push(e);
+  }
   return items;
 }
 
@@ -341,4 +503,4 @@ function stripHtml(s) {
   return s.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
 }
 
-module.exports = { tokenize, parseFeed, decodeEntities, localName, parseAttrs, stripHtml };
+module.exports = { tokenize, parseFeed, parseFeedDetailed, decodeEntities, localName, parseAttrs, stripHtml };