From 9fa70d0cb288acc38796665e5b94d514b0e3b2e0 Mon Sep 17 00:00:00 2001
From: nia-sg-bot <nia-sg-bot@users.noreply.github.com>
Date: Wed, 9 Sep 2026 15:04:48 +0530
Subject: [PATCH] feat(structural): locate parser failures in warnings

---
 diffgraph/structural.py                   | 23 ++++++++++++++++++++++-
 tests/fixtures/python_parser_failure.json |  2 +-
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/diffgraph/structural.py b/diffgraph/structural.py
index 47f5e1d..ab0e80f 100644
--- a/diffgraph/structural.py
+++ b/diffgraph/structural.py
@@ -215,6 +215,27 @@ def _is_type_alias_annotation(source: bytes, node) -> bool:
     return text in ("TypeAlias", "typing.TypeAlias")
 
 
+def _syntax_error_detail(root) -> str:
+    """Return the first parser-reported error location in source order.
+
+    Tree-sitter's root error flag tells us a snapshot is unsafe to turn into
+    topology, but users still need a deterministic, file-scoped clue for the
+    repair.  Traverse children in source order and report the first explicit
+    ERROR or missing node without attempting error recovery or inventing a
+    structural claim.
+    """
+    pending = [root]
+    while pending:
+        node = pending.pop()
+        if node.is_error or node.is_missing:
+            line, column = node.start_point
+            return "Tree-sitter reported a syntax error at line {}, column {}".format(
+                line + 1, column + 1
+            )
+        pending.extend(reversed(node.children))
+    return "Tree-sitter reported a syntax error"
+
+
 def _parse_python(
     content: bytes,
 ) -> Tuple[
@@ -229,7 +250,7 @@ def _parse_python(
     content.decode("utf-8")
     tree = _parser().parse(content)
     if tree.root_node.has_error:
-        raise ValueError("Tree-sitter reported a syntax error")
+        raise ValueError(_syntax_error_detail(tree.root_node))
 
     symbols: List[_Symbol] = []
     imports: List[_Import] = []
diff --git a/tests/fixtures/python_parser_failure.json b/tests/fixtures/python_parser_failure.json
index d6dd1b3..00755d6 100644
--- a/tests/fixtures/python_parser_failure.json
+++ b/tests/fixtures/python_parser_failure.json
@@ -16,7 +16,7 @@
       {
         "code": "PARSE_FAILURE",
         "file": "broken.py",
-        "detail": "post-change: ValueError: Tree-sitter reported a syntax error"
+        "detail": "post-change: ValueError: Tree-sitter reported a syntax error at line 1, column 12"
       }
     ]
   }