Confusion on reference and definition nodes

[maxwnewcomer]

For the following tsg grammar:

global FILE_NODE
    (function_definition
        name: (identifier) @id
        parameters: (parameters) @params
    ) @func {
        node def
        attr (def) type = "pop_symbol", symbol = (source-text @id), source_node = @func, is_definition
        edge FILE_NODE -> def
    }
    (identifier) @id {
        node id
        attr (id) type = "push_symbol", symbol = (source-text @id), is_reference, source_node = @id
        edge id -> FILE_NODE
    }

and python file

# test.py
def bar():
    pass
def foo():
    bar()

I get the following visualization:

The extra test.py node is probably an issue in my bfs directory build, and the grey node connected to root is the "test" folder i put "test.py".

I'm assuming a symbol node is not supposed to be both a reference and a definition, yet when creating with this tsg grammar it is. I'm assuming I'm supposed to only have one "bar" node as a push symbol and that would be the one referenced in foo(). I do know there is a "block" element of a function, but don't know how to access identifiers in that block. Is that how I'm supposed to create push symbols within a function?

I also think that examples in the docs of what types of nodes should be used for what scenarios would be extremely useful. The "technical" definition of what each node does and requires is there for sure, however, as a novice to using tree-sitter-stack-graph I am still a little confused.

For example an annotation of a given python file would be useful (at least for me):

#test.py
from y import x #push_scoped_symbol_node ???
def bar(): # pop_symbol_node ?
    pass
def foo(): # pop_symbol_node ?
    bar() #push_symbol_node ?

I'm sorry if this is a dumb question and if my understanding of what "scope" really means in the context of programming is too limited.

[hendrikvanantwerpen]

@maxwnewcomer A brief answer for now. I started adding some small, self-contained examples that highlight different name binding patterns here: https://github.com/github/stack-graphs/tree/main/tree-sitter-stack-graphs/examples. I hope to slowly grow this, bit I hope is useful to play with already!

[maxwnewcomer]

These are great, thank you so much @hendrikvanantwerpen !