index

Documentation

Overview

Package index implements ForgeADE Workspace Index (FWI): a lightweight indexing engine for editor features (go-to-definition, completion, outline) without depending on LSP or AI. It does no type checking or semantic analysis — those stay in the LSP domain.

Index

• func Register(p Parser)
• type DepSym
• type Export
• type File
• type FuncReturn
• type Import
• type Index
• type Language
  • func DetectLanguage(path string) Language
• type NewExpr
• type ParseResult
  • func Parse(src []byte, file *File) (*ParseResult, error)
• type Parser
  • func ForLang(lang Language) Parser
• type Scanner
  • func (s *Scanner) Scan() ([]string, error)
  • func (s *Scanner) ScanContext(ctx context.Context) ([]string, error)
• type Store
  • func New(dir string) *Store
  • func (s *Store) Build() error
  • func (s *Store) BuildContext(ctx context.Context) error
  • func (s *Store) Completion(prefix string, lang Language, path string) []Symbol
  • func (s *Store) Definition(name string) []Symbol
  • func (s *Store) Exports(file string) []Export
  • func (s *Store) Find(name string) []Symbol
  • func (s *Store) Imports(file string) []Import
  • func (s *Store) LanguageStats() (filesByLang, symsByLang map[string]int)
  • func (s *Store) Listen(bus *events.Bus) func()
  • func (s *Store) Load() error
  • func (s *Store) Members(instance, lang string) []Symbol
  • func (s *Store) Outline(file string) []Symbol
  • func (s *Store) Remove(path string) error
  • func (s *Store) Root() string
  • func (s *Store) Save() error
  • func (s *Store) Search(query string) []Symbol
  • func (s *Store) SnapshotDir() string
  • func (s *Store) Symbols() []Symbol
  • func (s *Store) Update(path string) error
• type Symbol
• type SymbolKind
  • func (k SymbolKind) String() string

Functions

func Register

func Register(p Parser)

Register adds a parser for a language. Last registration wins.

Types

type DepSym

type DepSym struct {
	Name string
	Kind SymbolKind
	Line int
}

DepSym is one exported name pulled from a dependency .d.ts.

type Export

type Export struct {
	FileID uint32
	Name   string
	Line   int
	Column int
}

Export is one export statement in a file (RFC §5.3).

type File

type File struct {
	ID       uint32
	Path     string
	Language Language
	Hash     uint64
}

File is a source file tracked by the index.

type FuncReturn

type FuncReturn struct {
	Name  string
	Class string   // return new Foo()
	Keys  []string // return { a, b }
	Line  int
}

FuncReturn records the shape a function returns: `return { ... }` or `return new Foo()` (RFC §7 functional-programming member completion).

type Import

type Import struct {
	FileID uint32
	Path   string // module path or relative path
	Names  []string
	Line   int
	Column int
}

Import is one import/require statement in a file (RFC §5.3).

type Index

type Index interface {
	Build() error
	Update(file string) error
	Remove(file string) error
	Symbols() []Symbol
	Find(name string) []Symbol
	Definition(name string) []Symbol
	Completion(prefix string) []Symbol
}

Index is the public FWI API (RFC §18).

type Language

type Language string

Language identifies a programming language (RFC §6).

const (
	LangJavaScript Language = "javascript"
	LangTypeScript Language = "typescript"
	LangJSX        Language = "jsx"
	LangTSX        Language = "tsx"
	LangGo         Language = "go"
	LangKotlin     Language = "kotlin"
	LangSwift      Language = "swift"
	LangPython     Language = "python"
	LangJava       Language = "java"
	LangDart       Language = "dart"
)

func DetectLanguage

func DetectLanguage(path string) Language

DetectLanguage maps a file path to a language, or "" if unsupported.

type NewExpr

type NewExpr struct {
	Name  string              // instance variable name
	Class string              // `new Foo()` or `: Foo` type annotation
	Fn    string              // `foo()` call → look up foo's return shape
	Keys  []string            // `{ a, b }` object literal keys (top level)
	Sub   map[string][]string // dotted subpath → keys, e.g. {"a":["b"], "a.b":["c"], "list[0]":["x"]}
	Alias string              // `x = otherVar` → follow otherVar's binding
	Line  int
}

NewExpr records what a `var x = ...` binding refers to, for member completion after `x.` (RFC §7). Only one of Class/Fn/Keys/Alias is set.

type ParseResult

type ParseResult struct {
	Symbols    []Symbol
	Imports    []Import
	Exports    []Export
	NewExprs   []NewExpr    // var bindings for member completion
	FuncReturn []FuncReturn // function return shapes for member completion
	Hash       uint64
}

ParseResult is what a Parser produces for a single file. Only symbols are stored in the index; AST is not retained (RFC §5.3).

func Parse

func Parse(src []byte, file *File) (*ParseResult, error)

Parse dispatches to the registered parser for file's language.

type Parser

type Parser interface {
	Language() Language
	Parse(src []byte, file *File) (*ParseResult, error)
}

Parser extracts symbols, imports and exports from a single source file (RFC §5.3). Parsers must be stateless: Parse may be called concurrently. New languages plug in via Register without touching the core indexer.

func ForLang

func ForLang(lang Language) Parser

ForLang returns the parser registered for lang, or nil.

type Scanner

type Scanner struct {
	// Root is the workspace directory to scan.
	Root string
	// Ignore adds extra directories (by base name) on top of defaults.
	Ignore map[string]bool
}

Scanner walks a workspace and yields source files (RFC §5.1). It only produces a list of files; parsing happens elsewhere.

func (*Scanner) Scan

func (s *Scanner) Scan() ([]string, error)

Scan returns parseable source file paths under Root, sorted. Files whose language has no registered parser are skipped.

func (*Scanner) ScanContext

func (s *Scanner) ScanContext(ctx context.Context) ([]string, error)

ScanContext returns parseable source file paths under Root with context cancellation support.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is an in-memory workspace index with optional snapshot persistence (RFC §10). It is safe for concurrent use.

func New

func New(dir string) *Store

New creates an empty index rooted at dir.

func (*Store) Build

func (s *Store) Build() error

Build performs a full scan-and-index of the workspace (RFC §5.1). Files are parsed by a worker pool sized to the CPU count (RFC §21).

func (*Store) BuildContext

func (s *Store) BuildContext(ctx context.Context) error

BuildContext performs a full scan-and-index of the workspace with cancellation support.

func (*Store) Completion

func (s *Store) Completion(prefix string, lang Language, path string) []Symbol

func (*Store) Definition

func (s *Store) Definition(name string) []Symbol

Definition returns the declaration sites for name (RFC §18).

func (*Store) Exports

func (s *Store) Exports(file string) []Export

Exports returns the export statements of a file (RFC §5.3).

func (*Store) Find

func (s *Store) Find(name string) []Symbol

Find returns symbols whose name matches exactly (RFC §18).

func (*Store) Imports

func (s *Store) Imports(file string) []Import

Imports returns the import statements of a file (RFC §5.3).

func (*Store) LanguageStats

func (s *Store) LanguageStats() (filesByLang, symsByLang map[string]int)

LanguageStats groups indexed files and symbols by language.

func (*Store) Listen

func (s *Store) Listen(bus *events.Bus) func()

Listen subscribes the store to workspace file events so the index stays in sync without full rescans (RFC §5.2): CREATE/UPDATE → parse & replace, DELETE → remove. Returns an unsubscribe function.

func (*Store) Load

func (s *Store) Load() error

Load restores the index from .workspace/index.bin if present.

func (*Store) Members

func (s *Store) Members(instance, lang string) []Symbol

func (*Store) Outline

func (s *Store) Outline(file string) []Symbol

Outline returns the symbols declared in a single file, sorted by line (RFC §14).

func (*Store) Remove

func (s *Store) Remove(path string) error

Remove drops a file and all its symbols from the index.

func (*Store) Root

func (s *Store) Root() string

Root returns the workspace directory.

func (*Store) Save

func (s *Store) Save() error

Save serializes the index to .workspace/index.bin and writes metadata.json.

func (*Store) Search

func (s *Store) Search(query string) []Symbol

Search returns symbols matching query using exact, prefix, camel-case and fuzzy matching, most precise first (RFC §15).

func (*Store) SnapshotDir

func (s *Store) SnapshotDir() string

SnapshotDir is where the index persists state (RFC §17) — globally under ~/.forge/index/<project> so no .workspace/ directory leaks into the workspace root. Legacy <root>/.workspace still loads via Load's fallback.

func (*Store) Symbols

func (s *Store) Symbols() []Symbol

Symbols returns all indexed symbols, sorted by file then line.

func (*Store) Update

func (s *Store) Update(path string) error

Update indexes a single file, replacing any previous symbols for it. If the file content hash is unchanged, parsing is skipped (RFC §9).

type Symbol

type Symbol struct {
	ID        string
	Name      string
	Kind      SymbolKind
	FileID    uint32
	File      string
	Line      int
	Column    int
	EndLine   int
	EndColumn int
	Scope     string // enclosing declaration name; empty at top level
	Exported  bool
	Module    string // non-empty = dependency export; import specifier e.g. "react"
}

Symbol is a single indexed declaration (RFC §7).

type SymbolKind

type SymbolKind int

SymbolKind categorizes a symbol (RFC §7).

const (
	Function SymbolKind = iota
	Class
	Interface
	Enum
	Struct
	TypeAlias
	Variable
	Constant
	Method
	Package
)

func (SymbolKind) String

func (k SymbolKind) String() string

String returns the stable lowercase name of the kind.