chore: release v0.3.0 (#38)

Author: tob-scott-a

README.md

@@ -90,7 +90,7 @@ flowchart TD
     class CG data
 ```
 
-Node IDs follow the scheme `module:function`, `module:Class`, or `module:Class.method` for unambiguous lookup. Edge confidence is tagged as `certain` (direct calls, `self.method()`), `inferred` (attribute access on non-self objects), or `uncertain` (dynamic dispatch).
+Node IDs follow the scheme `module:function`, `module:Class`, or `module:Class.method` for unambiguous lookup. Directory parsing resolves bare cross-file calls when a unique definition exists; ambiguous cross-file calls are left at their original best-effort target and marked `uncertain`. Edge confidence is tagged as `certain` (direct calls, `self.method()`), `inferred` (attribute access on non-self objects), or `uncertain` (dynamic dispatch or ambiguous resolution).
 
 ### 2. Index
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trailmark"
-version = "0.2.2"
+version = "0.3.0"
 description = "Parse source code into a queryable graph of functions, classes, calls, and semantic annotations"
 readme = "README.md"
 requires-python = ">=3.12"

src/trailmark/__init__.py

@@ -13,4 +13,4 @@
     "parse_file",
     "supported_languages",
 ]
-__version__ = "0.2.2"
+__version__ = "0.3.0"

src/trailmark/parsers/_common.py

@@ -121,6 +121,7 @@ def walk_source_files(
     """
     for root, dirs, files in os.walk(dir_path, followlinks=False):
         dirs[:] = [d for d in dirs if not should_skip_dir(d)]
+        dirs.sort()
         for fname in sorted(files):
             if any(fname.endswith(ext) for ext in extensions):
                 yield os.path.join(root, fname)
@@ -339,8 +340,9 @@ def _link_cross_file_calls(graph: CodeGraph) -> None:
         if len(candidates) == 1:
             new_edges.append(dataclasses.replace(edge, target_id=candidates[0]))
         else:
-            # Ambiguous — pick the candidate NOT in the caller's own module
-            # to prefer the cross-file definition over a same-file shadow.
+            # Ambiguous: prefer a single cross-file candidate when a same-file
+            # declaration is also present, but do not invent an arbitrary call
+            # target when multiple cross-file definitions share the same name.
             src_module = edge.source_id.rsplit(":", 1)[0] if ":" in edge.source_id else ""
             cross = [c for c in candidates if not c.startswith(src_module + ":")]
             if len(cross) == 1:
@@ -349,7 +351,6 @@ def _link_cross_file_calls(graph: CodeGraph) -> None:
                 new_edges.append(
                     dataclasses.replace(
                         edge,
-                        target_id=candidates[0],
                         confidence=EdgeConfidence.UNCERTAIN,
                     )
                 )

tests/test_common_parser.py

@@ -221,6 +221,21 @@ def _cross_file_parse(file_path: str) -> CodeGraph:
                 kind=EdgeKind.CALLS,
             )
         )
+    elif stem == "ambiguous_caller":
+        caller_id = f"{module_id}:invoke_shared"
+        nodes[caller_id] = CodeUnit(
+            id=caller_id,
+            name="invoke_shared",
+            kind=NodeKind.FUNCTION,
+            location=location,
+        )
+        edges.append(
+            CodeEdge(
+                source_id=caller_id,
+                target_id=f"{module_id}:shared_name",
+                kind=EdgeKind.CALLS,
+            )
+        )
 
     return CodeGraph(nodes=nodes, edges=edges, language="test", root_path=file_path)
 
@@ -278,3 +293,28 @@ def test_cross_file_linker_leaves_unresolvable_calls(tmp_path: Path) -> None:
     call_edges = [e for e in graph.edges if e.kind == EdgeKind.CALLS]
     assert len(call_edges) == 1
     assert call_edges[0].target_id == "caller:do_work"
+
+
+def test_cross_file_linker_keeps_ambiguous_cross_file_calls_unresolved(
+    tmp_path: Path,
+) -> None:
+    """Multiple cross-file definitions should not produce an arbitrary target."""
+    (tmp_path / "ambiguous1.c").write_text("")
+    (tmp_path / "ambiguous2.c").write_text("")
+    (tmp_path / "ambiguous_caller.c").write_text("")
+
+    graph = parse_directory(
+        _cross_file_parse,
+        language="test",
+        dir_path=str(tmp_path),
+        extensions=(".c",),
+    )
+
+    call_edges = [
+        e
+        for e in graph.edges
+        if e.kind == EdgeKind.CALLS and e.source_id == "ambiguous_caller:invoke_shared"
+    ]
+    assert len(call_edges) == 1
+    assert call_edges[0].target_id == "ambiguous_caller:shared_name"
+    assert call_edges[0].confidence == EdgeConfidence.UNCERTAIN

tests/test_readme.py

@@ -228,6 +228,10 @@ def test_readme_mentions_parse_only_api(self, readme_text: str) -> None:
         assert "from trailmark.parse import parse_directory, parse_file" in readme_text
         assert 'graph = parse_file("path/to/file.py")' in readme_text
 
+    def test_readme_documents_cross_file_call_resolution(self, readme_text: str) -> None:
+        assert "Directory parsing resolves bare cross-file calls" in readme_text
+        assert "ambiguous cross-file calls" in readme_text
+
 
 def _read_requires_python(pyproject_data: dict[str, object]) -> str:
     project_raw = pyproject_data.get("project")