query

Documentation

Overview

Package query implements the intelligence-layer query planner.

The planner maps (QueryType, language) → QueryPlan so callers (the MCP find_node tool, the evidence-pack assembler) know which retrieval path to take and which capability gaps to surface as degradation notes.

Mirrors src/main/java/io/github/randomcodespace/iq/intelligence/query/.

Index

• func AllCapabilities() map[string]CapabilityMatrix
• type CapabilityDimension
  • func AllDimensions() []CapabilityDimension
• type CapabilityLevel
• type CapabilityMatrix
  • func CapabilityMatrixFor(language string) CapabilityMatrix
• type Plan
  • func (p Plan) UsesGraph() bool
  • func (p Plan) UsesLexical() bool
• type Planner
  • func NewPlanner(capabilityFor func(string) CapabilityMatrix) *Planner
  • func (p *Planner) Plan(qt QueryType, language string) Plan
• type QueryRoute
  • func (q QueryRoute) String() string
• type QueryType

Functions

func AllCapabilities

func AllCapabilities() map[string]CapabilityMatrix

AllCapabilities returns the matrix for every language with a declared table. Keys are normalised lowercase language identifiers; insertion order follows the Java side's iteration order (deterministic). The returned maps are defensive copies.

Types

type CapabilityDimension

type CapabilityDimension string

CapabilityDimension names a semantic dimension of language intelligence used by the capability matrix. Mirrors Java intelligence/query/CapabilityDimension.java 1:1 — same enum identifiers.

const (
	// DimSymbolDefinitions — detection of symbol definitions (classes,
	// functions, methods, variables).
	DimSymbolDefinitions CapabilityDimension = "SYMBOL_DEFINITIONS"
	// DimSymbolReferences — detection of symbol references and usages
	// across files.
	DimSymbolReferences CapabilityDimension = "SYMBOL_REFERENCES"
	// DimImportResolution — resolution of import / require / use directives
	// to target symbols.
	DimImportResolution CapabilityDimension = "IMPORT_RESOLUTION"
	// DimTypeInfo — type information extraction (static types, inferred
	// types, generics).
	DimTypeInfo CapabilityDimension = "TYPE_INFO"
	// DimClassHierarchy — class hierarchy and interface / mixin
	// relationship detection.
	DimClassHierarchy CapabilityDimension = "CLASS_HIERARCHY"
	// DimFrameworkSemantics — framework-specific semantics (annotations,
	// decorators, conventions).
	DimFrameworkSemantics CapabilityDimension = "FRAMEWORK_SEMANTICS"
	// DimOrmEntityMapping — ORM entity and relationship mapping detection.
	DimOrmEntityMapping CapabilityDimension = "ORM_ENTITY_MAPPING"
	// DimAuthSecurity — authentication and authorization pattern detection.
	DimAuthSecurity CapabilityDimension = "AUTH_SECURITY"
	// DimAsyncPatterns — async, event-driven, and messaging pattern
	// detection.
	DimAsyncPatterns CapabilityDimension = "ASYNC_PATTERNS"
)

func AllDimensions

func AllDimensions() []CapabilityDimension

AllDimensions returns the full set of capability dimensions in declaration order. Returned as a defensive copy so callers can sort / mutate without touching package state.

type CapabilityLevel

type CapabilityLevel string

CapabilityLevel describes how well a given dimension is supported for a language. Mirrors Java intelligence/CapabilityLevel.java 1:1.

const (
	// LevelExact — full AST-level analysis (e.g. Java via JavaParser).
	LevelExact CapabilityLevel = "EXACT"
	// LevelPartial — grammar-based analysis with some structural gaps
	// (e.g. ANTLR-based languages).
	LevelPartial CapabilityLevel = "PARTIAL"
	// LevelLexicalOnly — regex / text-only detection.
	LevelLexicalOnly CapabilityLevel = "LEXICAL_ONLY"
	// LevelUnsupported — no detection at all for this language / dimension.
	LevelUnsupported CapabilityLevel = "UNSUPPORTED"
)

type CapabilityMatrix

type CapabilityMatrix map[CapabilityDimension]CapabilityLevel

CapabilityMatrix is a typed snapshot of capability levels per dimension. Aliased to a map so JSON marshaling produces the expected {dimension: level} shape without a custom MarshalJSON.

func CapabilityMatrixFor

func CapabilityMatrixFor(language string) CapabilityMatrix

CapabilityMatrixFor returns the per-language capability matrix. Returned matrix is a defensive copy — callers can mutate without contaminating the package-level tables. Mirrors Java CapabilityMatrix#forLanguage.

type Plan

type Plan struct {
	QueryType       QueryType        `json:"query_type"`
	Language        string           `json:"language"`
	Route           QueryRoute       `json:"route"`
	Capabilities    CapabilityMatrix `json:"capabilities"`
	DegradationNote string           `json:"degradation_note,omitempty"`
}

Plan is the planner's output for a given (queryType, language). Field names match the Java QueryPlan record so the JSON payload is structurally identical to the Java side.

func (Plan) UsesGraph

func (p Plan) UsesGraph() bool

UsesGraph reports whether the plan involves any graph traversal — true for GRAPH_FIRST and MERGED routes.

func (Plan) UsesLexical

func (p Plan) UsesLexical() bool

UsesLexical reports whether the plan involves lexical / text search — true for LEXICAL_FIRST and MERGED routes.

type Planner

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

Planner maps (queryType, language) → Plan deterministically. Mirrors Java intelligence/query/QueryPlanner.java — same priority chain: DEGRADED > LEXICAL_FIRST > MERGED > GRAPH_FIRST.

SEARCH_TEXT is always routed via LEXICAL_FIRST regardless of language — the graph does not index raw text content.

Planner is stateless and goroutine-safe — all state is captured in the capabilityFor closure passed at construction time.

func NewPlanner

func NewPlanner(capabilityFor func(string) CapabilityMatrix) *Planner

NewPlanner constructs a Planner that calls capabilityFor on every Plan invocation. Construct once at server startup and reuse — no internal state.

func (*Planner) Plan

func (p *Planner) Plan(qt QueryType, language string) Plan

Plan produces a QueryPlan for the given queryType + language. Result is fully deterministic for the same input.

type QueryRoute

type QueryRoute string

QueryRoute is the retrieval path picked by the Planner for a query intent + language. Mirrors Java intelligence/query/QueryRoute.java 1:1 — same names so the JSON envelope is structurally identical to the Java side.

const (
	// QueryRouteGraphFirst — primary path: query the structural graph (Kuzu).
	// Used when every relevant CapabilityDimension is EXACT — AST-level
	// analysis is available.
	QueryRouteGraphFirst QueryRoute = "GRAPH_FIRST"

	// QueryRouteLexicalFirst — fallback path: lexical / fulltext search only.
	// Used when every relevant CapabilityDimension is LEXICAL_ONLY — no
	// structural analysis is available for this language.
	QueryRouteLexicalFirst QueryRoute = "LEXICAL_FIRST"

	// QueryRouteMerged — combined path: graph results augmented with lexical
	// search. Used when at least one dimension is PARTIAL, or when a mix of
	// EXACT and LEXICAL_ONLY dimensions makes either alone insufficient.
	QueryRouteMerged QueryRoute = "MERGED"

	// QueryRouteDegraded — the feature is unsupported for this language.
	// QueryPlan.DegradationNote explains what is missing.
	QueryRouteDegraded QueryRoute = "DEGRADED"
)

func (QueryRoute) String

func (q QueryRoute) String() string

String returns the underlying identifier, which doubles as the JSON wire value. Required so the type satisfies fmt.Stringer for log output.

type QueryType

type QueryType string

QueryType captures the caller's intent. Mirrors the Java QueryType enum, same identifiers so degradation-note strings match byte-for-byte.

const (
	// QueryFindSymbol locates symbol definitions (classes, functions,
	// methods, variables) by name.
	QueryFindSymbol QueryType = "FIND_SYMBOL"

	// QueryFindReferences finds all usages / references of a symbol across
	// the indexed codebase.
	QueryFindReferences QueryType = "FIND_REFERENCES"

	// QueryFindCallers finds callers of a function or method.
	QueryFindCallers QueryType = "FIND_CALLERS"

	// QueryFindDependencies finds modules or packages a given module
	// depends on (via import / require / use resolution).
	QueryFindDependencies QueryType = "FIND_DEPENDENCIES"

	// QuerySearchText runs a full-text / lexical search across source files.
	// Always routes via QueryRouteLexicalFirst regardless of language.
	QuerySearchText QueryType = "SEARCH_TEXT"

	// QueryFindConfig locates configuration files and structured config
	// values (.env, application.yml, etc.).
	QueryFindConfig QueryType = "FIND_CONFIG"
)