describe

type Child ¶

type Child struct {
	Path      string `json:"path"`
	Kind      string `json:"kind"`
	FileCount int    `json:"file_count"`
	DeclCount int    `json:"decl_count"`
}

Child is one folder or file directly inside the described folder.

Only one level down is reported. A folder walk that returned everything underneath would hand back thousands of rows for a target like `internal`, and the caller cannot choose between thousands of rows — it can choose between eight. @intent let a caller descend one deliberate step at a time.

type Decl ¶

type Decl struct {
	NodeID        uint   `json:"node_id"`
	Name          string `json:"name"`
	QualifiedName string `json:"qualified_name"`
	Kind          string `json:"kind"`
	StartLine     int    `json:"start_line"`
	EndLine       int    `json:"end_line"`
	Intent        string `json:"intent,omitempty"`
}

Decl is one declaration written in a file. @intent give a reader a name, a place to open, and why it exists.

type Outline ¶

type Outline struct {
	Target       string       `json:"target"`
	Scope        Scope        `json:"scope"`
	Children     []Child      `json:"children,omitempty"`
	Declarations []Decl       `json:"declarations,omitempty"`
	Suggestions  []Suggestion `json:"suggestions,omitempty"`
}

Outline is everything the graph holds under one target.

Nothing here is ranked, scored, or filtered. That is the whole point: a search answer can be wrong about what matters, and an outline can only be wrong about what exists. Which field is filled is decided by Scope. @intent answer "what is in here" exactly, so the ranked tools do not have to.

type Repository ¶

type Repository interface {
	NodesByFile(ctx context.Context, filePath string) ([]graph.Node, error)
	PathNodes(ctx context.Context, folderPath string, kinds []graph.NodeKind) ([]graph.Node, error)
	NodesByExactName(ctx context.Context, name string, limit int) ([]graph.Node, error)
	Annotations(ctx context.Context, nodeIDs []uint) (map[uint]*graph.Annotation, error)
}

Repository supplies the namespace-scoped graph rows an outline is built from. @intent keep outline shaping independent of how the rows are queried.

type Scope ¶

type Scope string

Scope says which kind of thing the target turned out to name.

It is on the answer rather than on the request because a caller holding a string from somewhere else — a stack frame, a search hit, a diff — does not always know whether it points at a folder, a file, or nothing at all. @intent let one call answer for a folder, a file, or a miss, and say which it was.

const (
	ScopeDirectory Scope = "directory"
	ScopeFile      Scope = "file"
	// ScopeUnknown is the honest answer for a target the graph does not hold.
	// It is a case of the result rather than an error because the useful reply
	// to a mistyped or half-remembered name is a list of places that name lives.
	ScopeUnknown Scope = "unknown"
)

type Service ¶

type Service struct {
	Repository Repository
}

Service answers structural questions from stored graph rows. @intent provide one application entry point for "what is in here".

func New(repository Repository) *Service

func (s *Service) Describe(ctx context.Context, target string) (Outline, error)

type Suggestion ¶

type Suggestion struct {
	QualifiedName string `json:"qualified_name"`
	Kind          string `json:"kind"`
	FilePath      string `json:"file_path"`
	StartLine     int    `json:"start_line"`
}

Suggestion is one place a missed target's name actually lives. @intent turn a wrong path into the right one instead of into an empty answer.