abcoder

This document tracks historical issues encountered during the parsing of C++ code (specifically within freq_service v7) using the ABCoder C++ Collector. It details phenomena, root causes, and the status of fixes for issues related to template functions, NVI (Non-Virtual Interface) patterns, inheritance, and forward declarations.

Key Areas of Improvement

• Template Function Calls: Fixed issues where template function calls (e.g., main<...>(...)) were not being correctly identified as reference tokens, leading to failed dependency collection.
• Inheritance and Templates: Resolved bugs where Implements fields were empty for classes inheriting from template base classes (e.g., SimpleProvider<X,Y>). The collector now uses BaseClassRefs to parse base names directly from declarationText when standard definition lookups fail.
• NVI and Method Ownership: Fixed issues where methods using the NVI pattern or inline-in-class definitions had missing dependencies or incorrect NodeID assignments. The collector now correctly distinguishes between inline methods (where the receiver class body contains the method body) and out-of-line methods to avoid skipping dependency tokens.
• Forward Declarations: Fixed a bug where forward declarations (e.g., class X;) were incorrectly emitted as full Type nodes. The collector now filters these out by checking if the content contains a { brace.
• Alias Resolution: Improved support for using NS::Name; declarations to prevent incorrect NodeID construction (e.g., preventing app::Provider::Provider errors) by implementing resolveAlias and better alias detection in spec.go.

When processing Java, the ScannerByTreeSitter method performs the following steps:

1. Project Scanning: Parses pom.xml to find Maven module paths and traverses .java files.
2. File Parsing: Reads file content and calls javaparser.Parse(ctx, content) to generate a sitter.Tree.
3. LSP Notification: Calls c.cli.DidOpen(ctx, uri) to inform the LSP server the file is open.
4. AST Walking: Performs a depth-first traversal of the tree using c.walk(tree.RootNode(), ...). It identifies nodes by type (e.g., class_declaration, method_declaration) and creates preliminary DocumentSymbol objects containing syntax-based information (name, kind, and local range).

// Simplified version of the walk method in collect.go
func (c *Collector) walk(node *sitter.Node, ...) {
    switch node.Type() {
    case "class_declaration":
        // 1. Extract class name from the node
        nameNode := javaparser.FindChildIdentifier(node)
        name := nameNode.Content(content)

        // 2. Create a preliminary DocumentSymbol based on syntax info
        sym := &DocumentSymbol{
            Name: name,
            Kind: SKClass,
            Location: Location{URI: uri, Range: ...}, // Location within the current file
            Node: node, // Store the tree-sitter node
            Role: DEFINITION,
        }
        c.syms[sym.Location] = sym

        // 3. Recursively walk into the class body
        bodyNode := node.ChildByFieldName("body")
        if bodyNode != nil {
            for i := 0; i < int(bodyNode.ChildCount()); i++ {
                c.walk(bodyNode.Child(i), ...)
            }
        }
        return

    case "method_declaration":
        // ... similar logic for methods ...
    }
}

UAST is a unified intermediate representation used to represent multi-language code as a graph structure. It abstracts different programming languages into a common set of entities and relationships, enabling cross-language analysis.

Top-Level Hierarchy

• Repository: The highest level, containing one or more Modules.
• Module: An independent code unit (e.g., a Go Module, Java Maven project, or Python package).
• Package: A language-specific namespace (e.g., Go package or Java package).
• File: A physical source code file.

Core Entities: Node

Every Node represents a named entity in the code. Nodes are categorized by NodeType:

• FUNC: Functions or methods.
• TYPE: Classes, structs, interfaces, enums, etc.
• VAR: Global variables or constants.

Identity

Each node is uniquely identified by an Identity string in the format: ModPath?PkgPath#Name

• ModPath: Module path (e.g., github.com/your/project@v1.2.0)
• PkgPath: Package path (e.g., github.com/your/project/internal/utils)
• Name: Entity name (e.g., MyFunction, MyStruct.MyMethod)

In the UNIAST v0.1.3 mapping strategy used by the TypeScript parser, the concepts of 'Module' and 'Package' differ from standard npm terminology. Understanding this distinction is critical for interpreting the structure of the parsed AST:

Module (Represents an npm package)

• Definition: A directory containing a package.json.
• Name/Version: Derived from the package.json fields.
• Dir: The relative path from the repository root.
• Dependencies: Extracted from dependencies and devDependencies in package.json.
• Language: Always an empty string ('') for TypeScript modules.

Package (Represents an individual file)

• Definition: Every individual TypeScript or JavaScript file is treated as a separate Package.
• PkgPath: The file path relative to the module root (e.g., src/utils.ts).
• IsMain: A boolean indicating if the file is a main entry point (e.g., index.ts, main.ts).
• IsTest: A boolean indicating if the file is a test file (e.g., *.test.ts, *.spec.ts, or located in test/ or __tests__/ directories).