Conversation
vinistock
added
the
documentation
Graphite App
There was a problem hiding this comment.
I think Declaration should be declined into Class, Module, etc.
| A **Definition** represents a single source-level construct found at a specific location in the code. It captures key | ||
| information from the AST without making major transformations or assumptions about runtime behavior. Definitions are | ||
| captured during extraction. |
There was a problem hiding this comment.
I'm not sure I understand the last, are we talking about indexing?
| A **Definition** represents a single source-level construct found at a specific location in the code. It captures key | |
| information from the AST without making major transformations or assumptions about runtime behavior. Definitions are | |
| captured during extraction. | |
| A **Definition** represents a single source-level construct found at a specific location in the code. It captures key | |
| information from the AST without making major transformations or assumptions about runtime behavior. Definitions are | |
| captured during indexing. |
| ``` | ||
|
|
||
| **Definitions** (4 total - what the indexer discovers): | ||
| **Definitions** (4 total - what extraction discovers): |
There was a problem hiding this comment.
Okay, it looks like we're renaming the second phase.
What if we named the phases after what they creates? 🤔
listingbecomesdocuments, or maybeurisorpathsindexerbecomesdefinitionsresolutionbecomesdeclarations
There was a problem hiding this comment.
I'm honestly not a fan. I'd stick with names that try to describe the phase rather than just use its outputs.
| @@ -0,0 +1,49 @@ | |||
| # Extraction | |||
There was a problem hiding this comment.
I'd rather have one long file than a few short ones. It makes it easier to search.
| clarify at the goal of the steps. | ||
|
|
||
| - Indexing: stage for building the knowledge about the codebase | ||
| - Phase 1: [Extraction](extraction.md) |
There was a problem hiding this comment.
There is a phase before were we collect all the files we'll index
| @@ -0,0 +1,49 @@ | |||
| # Extraction | |||
|
|
|||
| During extraction, source code is parsed into ASTs and key information is recorded to be transformed and used in | |||
There was a problem hiding this comment.
Do we actually do any "transformation"?
| semantics. | ||
|
|
||
| The intention is to be able to work backwards to the original code since the goal is to support many different tools. | ||
| As an example, considering an `unless` as an `if !` is generally correct for static analysis. However, it would not be |
There was a problem hiding this comment.
This may be confusing as we do not even look at method bodies.
What if we used the example of storing attributes as methods?
|
|
||
| - Creates `Definition` objects for classes, modules, methods, constants, variables | ||
| - Records source locations, comments, and lexical ownership (`owner_id`) | ||
| - Captures unresolved constant references (e.g., `Foo::Bar` as a `NameId`) |
There was a problem hiding this comment.
And also unresolved method references
|
|
||
| Trying to create a tree of dependencies ahead of time to resolve constants is difficult because some dependencies are | ||
| only identified when we are in the middle of performing resolution. Instead of taking that approach, the resolution | ||
| loop is an optimistically sorted worklist algorithm (inspired by [Sorbet's](https://github.com/sorbet/sorbet) approach). |
There was a problem hiding this comment.
Let's point to the exact file for reference
| where we go through the list of work. If we exhaust the worklist or fail to make any progress in a pass, then we | ||
| finalize the loop. | ||
|
|
||
| ```rust |
There was a problem hiding this comment.
At some point a diagram with boxes and arrows may be easier to follow. But let's leave this for later once everything stabilized.
vinistock
force-pushed
the
01-08-restructure_phase_documentation
branch
from
45b07fd to
148598c
Compare
2 participants
This PR does 3 things:
I made a few conceptual name changes:
I believe that makes it a bit clearer. We have indexing as a "stage" combining two phases. Let me know what you think!