ek9_find_constructs_by_name

Answers first: matchCount, then matches[] (name, fullyQualifiedName, module, genus, file, line, column) - workspace-wide; matches:[] when no top-level construct has that name.

Category: Enquiry · Compare: Search Everywhere (IntelliJ) / Go to Symbol in Workspace (VSCode)

When to use it

Where is a construct named X declared (file, line, module) - one call with name:'X', or name:'Cust*' for a case-insensitive prefix.

When not to use it

The construct's detail rather than its location - ek9_query_construct, ek9_query_type_hierarchy, ek9_query_effective_api and ek9_query_call_graph all take symbol:'X' directly, no lookup first.
A built-in language type (String, List, Optional, …) — those live in the language not the workspace; use ek9_help <Type> instead.
You already have file+line+column — no name lookup needed; use ek9_inspect_symbol_at_cursor.
Not a name lookup at all: free-text search over source content (comments, strings) is ek9_search_text; a whole-workspace overview is ek9_query_workspace.

Details

Mode is selected purely by the value: exact case-sensitive match by default, case-insensitive prefix with a trailing `*` (a bare `*` is an error, not a list-all). Each match carries name, fullyQualifiedName (module `::` construct — preserve the `::` when chaining), module (always the DEFINING module; matches deduplicated by FQN), genus, file (workspace-relative), line and 0-based column. No matches is success with matchCount:0 and matches:[], never an error; requires the workspace to have reached SYMBOL_DEFINITION.

Arguments

Argument	Type	Required	What it is
`name`	string	yes	Unqualified name to search for. Append `` for case-insensitive prefix matching (e.g. "Cust"). Without `*`, exact case-sensitive match.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it.

Find by exact name shape

Request

{
  "name" : "MyRecord"
}

Response

{
  "matchCount" : 1,
  "matches" : [ {
    "column" : 4,
    "file" : "MyRecord.ek9",
    "fullyQualifiedName" : "com.example::MyRecord",
    "genus" : "RECORD",
    "line" : 5,
    "module" : "com.example",
    "name" : "MyRecord"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "mode" : "exact",
  "query" : "MyRecord",
  "status" : "ok"
}

Nothing named is not found

Request

{
  "name" : "Hexagon"
}

Response

{
  "matchCount" : 0,
  "matches" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "mode" : "exact",
  "nextStep" : "ek9_find_constructs_by_name name:'Hexagon*' for every construct whose name starts with it",
  "note" : "No construct is named 'Hexagon' in the workspace (exact, case-sensitive)",
  "query" : "Hexagon",
  "status" : "not-found"
}