vigil-codeintel 0.1.0__py3-none-any.whl

vigil_mapper/source_adapters/_lexer.py

@@ -0,0 +1,309 @@
+"""Shared preprocessing utilities for regex-based source adapters.
+
+L2 implementation: C-family comment & string stripping plus multi-line import
+collapsing for TypeScript / JavaScript. Single-pass character-by-character
+scanner in ``strip_comments_and_strings`` -- O(n), stdlib only, no external
+parser dependency.
+
+Python adapter does NOT use this module -- it calls ``ast.parse`` directly.
+
+Language argument is retained in the signature for future L5 dispatch
+(Go / Java share the C-family rules) but currently only ``"typescript"``,
+``"javascript"`` are recognised. Unknown languages fall back to a safe
+passthrough (caller still works, just with comment/string false-positives).
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+__all__ = [
+    "strip_comments_and_strings",
+    "strip_comments_only",
+    "join_multiline_imports",
+    "strip_go_raw_strings",
+]
+
+_log = logging.getLogger(__name__)
+
+# Languages that share C-family comment + string syntax.
+_C_FAMILY: frozenset[str] = frozenset({"typescript", "javascript", "go", "java"})
+
+
+def strip_comments_only(content: str, language: str) -> str:
+    """Remove line and block comments while PRESERVING string literals intact.
+
+    Used by ``extract_imports`` where the module specifier IS a string body
+    (``from 'react'``) -- we must not destroy it. String literals are still
+    scanned so that a comment opener inside a string (e.g. ``"http://x"``)
+    does not accidentally trigger comment stripping.
+
+    Unknown languages fall back to a passthrough.
+    """
+    if language not in _C_FAMILY:
+        return content
+
+    out: list[str] = []
+    i = 0
+    n = len(content)
+
+    while i < n:
+        ch = content[i]
+        nxt = content[i + 1] if i + 1 < n else ""
+
+        # Line comment //...
+        if ch == "/" and nxt == "/":
+            j = content.find("\n", i + 2)
+            if j == -1:
+                break
+            out.append("\n")
+            i = j + 1
+            continue
+
+        # Block comment /* ... */
+        if ch == "/" and nxt == "*":
+            j = content.find("*/", i + 2)
+            if j == -1:
+                for c in content[i:]:
+                    if c == "\n":
+                        out.append("\n")
+                break
+            for c in content[i:j + 2]:
+                if c == "\n":
+                    out.append("\n")
+            i = j + 2
+            continue
+
+        # String literal — preserve contents verbatim but skip past so a
+        # ``//`` / ``/*`` inside the body cannot trigger comment stripping.
+        if ch in ("'", '"', "`"):
+            quote = ch
+            out.append(quote)
+            i += 1
+            while i < n:
+                c = content[i]
+                if c == "\\" and i + 1 < n:
+                    out.append(c)
+                    out.append(content[i + 1])
+                    i += 2
+                    continue
+                out.append(c)
+                if c == quote:
+                    i += 1
+                    break
+                i += 1
+            continue
+
+        out.append(ch)
+        i += 1
+
+    return "".join(out)
+
+
+def strip_comments_and_strings(content: str, language: str) -> str:
+    """Remove comment and string literal regions from *content*.
+
+    Replaces:
+        - ``//`` line comments -> emit the trailing newline untouched.
+        - ``/* ... */`` block comments -> emit newlines that fell inside.
+        - ``'...'`` / ``"..."`` / `` `...` `` string spans -> emit empty body
+          (quotes preserved) plus any internal newlines.
+
+    Escape sequences (``\\"``, ``\\'``, ``\\\\``, ``\\n``, etc.) inside strings
+    do NOT terminate the string. Template literals are treated as simple
+    strings for L2 -- nested ``${...}`` expressions are NOT re-parsed.
+
+    Newlines are always preserved so that ``re.MULTILINE`` patterns matching
+    against the cleaned output still recover correct 1-based line numbers.
+
+    Unknown languages fall back to a passthrough (returns *content* unchanged)
+    -- L2 covers only ``typescript`` and ``javascript``.
+    """
+    if language not in _C_FAMILY:
+        return content
+
+    out: list[str] = []
+    i = 0
+    n = len(content)
+
+    while i < n:
+        ch = content[i]
+        nxt = content[i + 1] if i + 1 < n else ""
+
+        # Line comment //...\n
+        if ch == "/" and nxt == "/":
+            j = content.find("\n", i + 2)
+            if j == -1:
+                # Comment runs to EOF; emit nothing more.
+                break
+            # Preserve the newline so line numbers stay aligned.
+            out.append("\n")
+            i = j + 1
+            continue
+
+        # Block comment /* ... */
+        if ch == "/" and nxt == "*":
+            j = content.find("*/", i + 2)
+            if j == -1:
+                # Unterminated block comment runs to EOF — swallow, preserve
+                # any embedded newlines so line counts don't collapse.
+                for c in content[i:]:
+                    if c == "\n":
+                        out.append("\n")
+                break
+            # Preserve embedded newlines within the comment.
+            for c in content[i:j + 2]:
+                if c == "\n":
+                    out.append("\n")
+            i = j + 2
+            continue
+
+        # String literals
+        if ch in ("'", '"', "`"):
+            quote = ch
+            out.append(quote)
+            i += 1
+            while i < n:
+                c = content[i]
+                if c == "\\" and i + 1 < n:
+                    # Skip the escape + escaped char. Don't emit either into
+                    # the body (body is intentionally empty), but preserve
+                    # a newline only if the escape targets a literal newline.
+                    esc = content[i + 1]
+                    if esc == "\n":
+                        out.append("\n")
+                    i += 2
+                    continue
+                if c == quote:
+                    out.append(quote)
+                    i += 1
+                    break
+                if c == "\n":
+                    # Preserve newline. Note: unescaped newlines in '...'/"..."
+                    # are a syntax error in TS/JS, but template literals allow
+                    # them. Either way we keep line counts correct.
+                    out.append("\n")
+                    i += 1
+                    continue
+                # Regular character inside string: drop (body becomes empty).
+                i += 1
+            else:
+                # EOF reached without closing quote — bail cleanly.
+                _log.debug(
+                    "strip_comments_and_strings: unterminated %s string literal",
+                    quote,
+                )
+            continue
+
+        # Regular source character.
+        out.append(ch)
+        i += 1
+
+    return "".join(out)
+
+
+# Matches ``import { ... } from 'x'`` (or `"x"`) or the re-export form
+# ``export { ... } from 'x'`` where the brace group may span multiple lines.
+# ``from '...'`` is MANDATORY — this prevents the regex from swallowing
+# unrelated brace groups like ``export class Foo {}`` or
+# ``export function bar() { ... }``.
+# Captured groups:
+#   1: leading keyword phrase up to and including the opening brace
+#   2: multi-line brace body (non-greedy, without braces)
+#   3: trailing portion including ``from 'x'`` or ``from "x"``
+_MULTILINE_BRACE_IMPORT = re.compile(
+    r"(^[ \t]*(?:import|export)[^\n{]*?\{)"          # keyword ... {
+    r"([^{}]*?)"                                      # body (no braces)
+    r"(\}[ \t]*from[ \t]*['\"][^'\"\n]+['\"][ \t]*;?)",  # } from '...' ;
+    re.MULTILINE | re.DOTALL,
+)
+
+
+def join_multiline_imports(content: str, language: str) -> str:
+    """Collapse multi-line brace-group imports onto a single logical line.
+
+    Transforms::
+
+        import {
+            ComponentA,
+            ComponentB,
+        } from './components';
+
+    into::
+
+        import {  ComponentA, ComponentB, } from './components';
+
+    Leading indentation is preserved so the ``import`` keyword stays at the
+    same 1-based line number (any embedded newlines inside the brace group
+    are simply replaced with a single space). Lines preceding and following
+    the statement are untouched, so downstream regex matchers that count via
+    ``re.MULTILINE`` still report the original ``import`` line number.
+
+    Unknown languages fall back to a passthrough.
+    """
+    if language not in _C_FAMILY:
+        return content
+
+    def _collapse(match: re.Match[str]) -> str:
+        head, body, tail = match.group(1), match.group(2), match.group(3)
+        # Count newlines that fall between the opening '{' and the ';' (or
+        # line-end). We collapse them into a single space inside the brace
+        # group, but append them AFTER the statement so the line number of
+        # every subsequent ``import`` keyword — and every later symbol — is
+        # preserved byte-for-byte against the original source.
+        original = match.group(0)
+        nl_count = original.count("\n")
+        flat = re.sub(r"\s+", " ", body)
+        collapsed = f"{head} {flat.strip()} {tail}"
+        # Re-emit the newlines so downstream line numbers stay stable.
+        return collapsed + ("\n" * nl_count)
+
+    return _MULTILINE_BRACE_IMPORT.sub(_collapse, content)
+
+
+def strip_go_raw_strings(content: str) -> str:
+    """Replace Go backtick raw string bodies with empty bodies.
+
+    Go raw string literals are delimited by backticks (`` ` ``).  They
+    have NO escape sequences -- a backtick cannot appear inside the literal.
+    The entire span from opening to closing backtick is therefore replaced by
+    two consecutive backtick characters, preserving any embedded newlines as
+    plain newlines so that downstream line-number counts remain stable.
+
+    This function must be applied BEFORE ``strip_comments_only`` when
+    processing Go source for import extraction, because ``strip_comments_only``
+    preserves string bodies verbatim (needed for ``"..."`` import paths) and
+    would otherwise keep the backtick body intact -- allowing fake imports
+    embedded in raw string literals to produce false-positive ImportEdges.
+
+    Usage::
+
+        cleaned = strip_go_raw_strings(source)
+        cleaned = strip_comments_only(cleaned, "go")
+    """
+    out: list[str] = []
+    i = 0
+    n = len(content)
+
+    while i < n:
+        ch = content[i]
+        if ch == "`":
+            # Opening backtick — scan until closing backtick (no escapes).
+            out.append("`")
+            i += 1
+            while i < n:
+                c = content[i]
+                i += 1
+                if c == "`":
+                    # Closing backtick — emit it and stop.
+                    out.append("`")
+                    break
+                if c == "\n":
+                    # Preserve newlines to keep line numbers correct.
+                    out.append("\n")
+                # All other characters in the raw string are dropped.
+        else:
+            out.append(ch)
+            i += 1
+
+    return "".join(out)

vigil_mapper/source_adapters/_patterns.py

@@ -0,0 +1,212 @@
+"""Shared regex patterns for TypeScript / JavaScript adapters.
+
+Factoring out keeps the adapter modules under the 400-line budget and
+guarantees that TS and JS behave identically on overlapping syntax
+(ES-module import/export, top-level class/function declarations).
+
+All patterns operate on *cleaned* source -- i.e. output of
+``_lexer.strip_comments_and_strings`` then ``_lexer.join_multiline_imports``.
+String bodies are therefore empty (``''`` / ``""`` / `` `` ``) and comments
+are gone, which prevents ``//`` or ``/* import fake */`` from matching.
+"""
+from __future__ import annotations
+
+import re
+import logging
+_log = logging.getLogger(__name__)
+
+__all__ = [
+    "RE_IMPORT_DEFAULT",
+    "RE_IMPORT_NAMED",
+    "RE_IMPORT_NAMESPACE",
+    "RE_IMPORT_SIDE_EFFECT",
+    "RE_IMPORT_TYPE_DEFAULT",
+    "RE_IMPORT_TYPE_NAMED",
+    "RE_EXPORT_FROM_NAMED",
+    "RE_EXPORT_FROM_STAR",
+    "RE_DYNAMIC_IMPORT",
+    "RE_REQUIRE_ASSIGN",
+    "RE_REQUIRE_BARE",
+    "RE_SYMBOL_CLASS",
+    "RE_SYMBOL_INTERFACE",
+    "RE_SYMBOL_TYPE",
+    "RE_SYMBOL_FUNCTION",
+    "RE_SYMBOL_CONST",
+    "RE_SYMBOL_ENUM",
+    "classify_import",
+]
+
+
+# ---------------------------------------------------------------------------
+# Import-form regex patterns (ES modules)
+# ---------------------------------------------------------------------------
+#
+# Conventions:
+#   - ``^`` anchors every pattern to start-of-line (re.MULTILINE) so that
+#     nested ``import(...)`` inside a function body is still caught by the
+#     dynamic-import pattern below (which is NOT line-anchored).
+#   - Target module is captured as group ``module``.
+#   - Quotes may be single or double. Template-literal imports are not
+#     recognised here (rare; low confidence; explicit tech-debt for L6).
+
+# ``import X from 'Y'``  (default only)
+RE_IMPORT_DEFAULT = re.compile(
+    r"""^[ \t]*import\s+
+        (?!type\b)                                    # skip 'import type ...'
+        [A-Za-z_$][\w$]*                              # default binding
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``import { A, B } from 'Y'`` (named only, maybe with default prefix)
+RE_IMPORT_NAMED = re.compile(
+    r"""^[ \t]*import\s+
+        (?!type\b)
+        (?:[A-Za-z_$][\w$]*\s*,\s*)?                  # optional default binding
+        \{[^}]*\}                                      # named group (may be empty)
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``import * as X from 'Y'``
+RE_IMPORT_NAMESPACE = re.compile(
+    r"""^[ \t]*import\s+
+        \*\s+as\s+[A-Za-z_$][\w$]*
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``import 'Y'`` (side-effect only)
+RE_IMPORT_SIDE_EFFECT = re.compile(
+    r"""^[ \t]*import\s+['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``import type X from 'Y'`` (TS-only)
+RE_IMPORT_TYPE_DEFAULT = re.compile(
+    r"""^[ \t]*import\s+type\s+
+        [A-Za-z_$][\w$]*
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``import type { X } from 'Y'`` (TS-only)
+RE_IMPORT_TYPE_NAMED = re.compile(
+    r"""^[ \t]*import\s+type\s+
+        \{[^}]*\}
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``export { A, B } from 'Y'`` (re-export)
+RE_EXPORT_FROM_NAMED = re.compile(
+    r"""^[ \t]*export\s+
+        \{[^}]*\}
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# ``export * from 'Y'`` or ``export * as NS from 'Y'``
+RE_EXPORT_FROM_STAR = re.compile(
+    r"""^[ \t]*export\s+
+        \*(?:\s+as\s+[A-Za-z_$][\w$]*)?
+        \s+from\s+
+        ['"](?P<module>[^'"\n]+)['"]\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# Dynamic ``import('Y')`` — NOT line-anchored; may appear inside expressions.
+RE_DYNAMIC_IMPORT = re.compile(
+    r"""\bimport\s*\(\s*
+        ['"](?P<module>[^'"\n]+)['"]
+        \s*\)""",
+    re.VERBOSE,
+)
+
+# CommonJS: ``const|let|var X = require('Y')`` (assignment form)
+RE_REQUIRE_ASSIGN = re.compile(
+    r"""^[ \t]*(?:const|let|var)\s+
+        (?:[A-Za-z_$][\w$]*|\{[^}]*\}|\[[^\]]*\])      # binding (ident | destructure)
+        \s*=\s*require\s*\(\s*
+        ['"](?P<module>[^'"\n]+)['"]
+        \s*\)\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+# CommonJS bare: ``require('Y');`` (side-effect)
+RE_REQUIRE_BARE = re.compile(
+    r"""^[ \t]*require\s*\(\s*
+        ['"](?P<module>[^'"\n]+)['"]
+        \s*\)\s*;?\s*$""",
+    re.MULTILINE | re.VERBOSE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Symbol-definition regex patterns — top-level only
+# ---------------------------------------------------------------------------
+#
+# Top-level is approximated by requiring the declaration keyword to start at
+# column zero, optionally preceded by ``export `` / ``export default ``.
+# Indented declarations inside function bodies, classes, or blocks are not
+# captured — this is intentional for L2 (avoids nested noise; deep parsing
+# is a tree-sitter job for L6+).
+
+_EXPORT_PREFIX = r"(?P<export>export\s+(?:default\s+)?)?"
+_TOPLEVEL_START = r"^" + _EXPORT_PREFIX
+
+RE_SYMBOL_CLASS = re.compile(
+    _TOPLEVEL_START
+    + r"(?:abstract\s+)?class\s+(?P<name>[A-Za-z_$][\w$]*)",
+    re.MULTILINE,
+)
+
+RE_SYMBOL_INTERFACE = re.compile(
+    _TOPLEVEL_START + r"interface\s+(?P<name>[A-Za-z_$][\w$]*)",
+    re.MULTILINE,
+)
+
+RE_SYMBOL_TYPE = re.compile(
+    _TOPLEVEL_START + r"type\s+(?P<name>[A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\s*=",
+    re.MULTILINE,
+)
+
+RE_SYMBOL_FUNCTION = re.compile(
+    _TOPLEVEL_START
+    + r"(?:async\s+)?function\s*\*?\s*(?P<name>[A-Za-z_$][\w$]*)\s*\(",
+    re.MULTILINE,
+)
+
+RE_SYMBOL_CONST = re.compile(
+    _TOPLEVEL_START
+    + r"(?:const|let|var)\s+(?P<name>[A-Za-z_$][\w$]*)\s*[:=]",
+    re.MULTILINE,
+)
+
+RE_SYMBOL_ENUM = re.compile(
+    _TOPLEVEL_START
+    + r"(?:const\s+)?enum\s+(?P<name>[A-Za-z_$][\w$]*)",
+    re.MULTILINE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def classify_import(module: str) -> str:
+    """Return ``"relative"`` for dot-prefixed specifiers, else ``"absolute"``.
+
+    Matches Node ESM / TS convention: a specifier starting with ``.`` or
+    ``..`` (or ``/``) is relative to the file; anything else -- including
+    scoped packages like ``@scope/pkg`` and node: builtins -- is absolute.
+    """
+    if module.startswith(".") or module.startswith("/"):
+        return "relative"
+    return "absolute"

vigil_mapper/source_adapters/_treesitter.py

@@ -0,0 +1,182 @@
+"""Shared tree-sitter helpers for source adapters.
+
+Provides a cached parser factory and ergonomic utilities for walking
+tree-sitter parse trees.  Language-neutral — designed for reuse by Go,
+Java, JavaScript, TypeScript adapters and any future tree-sitter adapter.
+
+Public API
+----------
+get_ts_parser(language)
+    Return a cached ``tree_sitter.Parser`` initialised for *language*.
+    Supported language names match those accepted by
+    ``tree_sitter_language_pack.get_language``.
+
+parse_bytes(language, source_bytes)
+    Convenience: parse *source_bytes* and return the root ``Node``.
+
+node_text(node, source_bytes)
+    Decode the byte slice that corresponds to *node* in *source_bytes*.
+
+node_line(node)
+    Return the 1-based source line number for *node*.
+
+iter_named_children(node, *types)
+    Yield direct named children of *node* whose ``type`` is in *types*.
+    If no types are given, yield all named children.
+
+walk_named(node, *types)
+    Depth-first generator over ALL named descendant nodes (including
+    *node* itself) whose ``type`` is in *types*.
+    If no types are given, yield all named descendants.
+
+Verified against tree-sitter==0.25.2 / tree-sitter-language-pack==1.10.8.
+Parser is constructed as ``Parser(get_language(lang))`` — the ``get_parser``
+wrapper is ABI-broken on 0.25 and must NOT be used.
+"""
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Generator
+
+from tree_sitter import Node, Parser
+from tree_sitter_language_pack import get_language
+
+__all__ = [
+    "get_ts_parser",
+    "parse_bytes",
+    "node_text",
+    "node_line",
+    "iter_named_children",
+    "walk_named",
+]
+
+_log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Parser cache
+# ---------------------------------------------------------------------------
+
+@lru_cache(maxsize=32)
+def get_ts_parser(language: str) -> Parser:
+    """Return a cached ``Parser`` initialised for *language*.
+
+    Uses ``Parser(get_language(language))`` — the verified form for
+    tree-sitter==0.25.  The result is cached per language string so
+    adapters instantiated many times pay the initialisation cost only once.
+
+    Parameters
+    ----------
+    language:
+        Language name understood by ``tree_sitter_language_pack``,
+        e.g. ``"go"``, ``"java"``, ``"javascript"``, ``"typescript"``.
+
+    Raises
+    ------
+    LookupError
+        If *language* is not available in the installed language pack.
+    """
+    lang_obj = get_language(language)
+    parser = Parser(lang_obj)
+    _log.debug("tree-sitter parser created for language=%r", language)
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Parse convenience
+# ---------------------------------------------------------------------------
+
+def parse_bytes(language: str, source_bytes: bytes) -> Node:
+    """Parse *source_bytes* with the cached parser for *language*.
+
+    Parameters
+    ----------
+    language:
+        Language name (see :func:`get_ts_parser`).
+    source_bytes:
+        Raw UTF-8 encoded source code.
+
+    Returns
+    -------
+    Node
+        The ``root_node`` of the parsed tree.
+    """
+    parser = get_ts_parser(language)
+    tree = parser.parse(source_bytes)
+    return tree.root_node
+
+
+# ---------------------------------------------------------------------------
+# Node utilities
+# ---------------------------------------------------------------------------
+
+def node_text(node: Node, source_bytes: bytes) -> str:
+    """Return the source text slice that corresponds to *node*.
+
+    Decodes as UTF-8 (errors replaced) so callers always get a ``str``.
+    """
+    return source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+
+
+def node_line(node: Node) -> int:
+    """Return the 1-based line number of *node* in the source file.
+
+    tree-sitter stores ``start_point`` as a ``(row, column)`` tuple where
+    ``row`` is 0-based; we add 1 to match the convention used throughout
+    the adapter IR.
+    """
+    return node.start_point[0] + 1
+
+
+def iter_named_children(node: Node, *types: str) -> Generator[Node, None, None]:
+    """Yield direct named children of *node* filtered by ``type``.
+
+    Parameters
+    ----------
+    node:
+        Parent node whose children to iterate.
+    *types:
+        Optional whitelist of node type strings.  If omitted, all named
+        children are yielded.
+
+    Yields
+    ------
+    Node
+        Named child nodes matching the type filter.
+    """
+    type_set: frozenset[str] | None = frozenset(types) if types else None
+    for child in node.children:
+        if not child.is_named:
+            continue
+        if type_set is None or child.type in type_set:
+            yield child
+
+
+def walk_named(node: Node, *types: str) -> Generator[Node, None, None]:
+    """Depth-first generator over all named descendants of *node*.
+
+    *node* itself is included if it matches the type filter.
+
+    Parameters
+    ----------
+    node:
+        Starting node (included in traversal).
+    *types:
+        Optional whitelist of node type strings.  If omitted, all named
+        nodes are yielded.
+
+    Yields
+    ------
+    Node
+        Named descendant nodes matching the type filter.
+    """
+    type_set: frozenset[str] | None = frozenset(types) if types else None
+    stack = [node]
+    while stack:
+        current = stack.pop()
+        if current.is_named and (type_set is None or current.type in type_set):
+            yield current
+        # Push children in reverse so left-to-right DFS order is preserved.
+        for child in reversed(current.children):
+            stack.append(child)