ek9_query_references

Answers first: useSiteCount, usedByConstructs, useSites as file.ek9:LINE - then each reference with its source line (omitted above 50 sites unless verbosity:'full').

Category: Enquiry · Compare: Find Usages (IntelliJ) / Find All References (VSCode)

When to use it

'Who uses X, and from which constructs' is one call with symbol:'Type.member' - no file needed; the pre-flight for rename, safe-delete and change-signature.

When not to use it

a method's incoming AND outgoing call structure in one query (use ek9_query_call_graph)
what a type EXPOSES or how it RELATES (supertypes/subtypes/traits), not where it is used (use ek9_query_effective_api or ek9_query_type_hierarchy)
raw text occurrences (comments, string literals) (use ek9_search_text; this tool resolves structural references via the type system)

Details

Anchor symbol may be any kind the compiler tracks: types, methods, functions, fields, constants, and locals / parameters / returning params inside a body. Two distinct enums on the response: top-level 'kind' is uppercase (METHOD, FIELD, TYPE…); per-reference 'kind' is lowercase snake_case — declaration (always first), structural (extends, trait_implementation, field_type, parameter_type, return_type…), calls (method_call, function_call, constructor_call) and identity-match body usages (variable_usage, parameter_usage, field_access, constant_usage…). A use of a VARIABLE (field, parameter, local, returning variable, constant) carries access:'read' or access:'write' (with writeOperator), and the headline gives writeSiteCount and writeSites - who CHANGES it. A write is an assignment (':', ':=', '=', ':=?') or a mutating operator ('+=', ':=:', ':~:', ':^:', '++', ...), so 'order.total += 5' is a write though it stores nothing to the field; a mutating METHOD call ('items.add(x)') is not. For a PROPERTY the writeSites are every line that can change its value on any instance (THE property write-site query): direct, through an alias ('t <- order.total; t += 5'), a view ('t <- order.getTotal()'), a method that is not pure on its object, or a user callee data touch says writes its parameter - writeSitesByRoute counts them and writes[] gives each with foundBy, operation, certain (false for view/method/callee: they MAY change it), through, fedBy and, for a callee, origin (where inside it the write is). A reference whose type was INFERRED (no text names the symbol: 'if product <- store.findProduct(id)' for Product) carries explicit:false - one per name that received the type - as does a method call on an instance for its type ('$product.getPriority()' does not spell Product); a site whose text names the symbol is explicit:true. When any are inferred the headline gives explicitUseSiteCount and inferredUseSiteCount; include:'explicit' keeps only the sites that name it. An overloaded 'Type.member' with no signature (a constructor 'Type.Type' included) answers for EVERY overload: useSites is their union and overloads[] holds each one's answer tagged with its signature, resendable as 'Type.m(P)'; when they form a dispatcher the name means its entry point. summary.productionVsTest is a PATH HEURISTIC (test = path contains a 'test' segment), not authoritative; a cursor on whitespace/comment/unresolvable returns status:'not-found', not an error.

Arguments

Argument	Type	What it is
`among`	array of string	Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched).
`column`	integer	0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from `ek9_inspect_symbol_at_cursor` verbatim.
`file`	string	The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.
`include`	string: all \| explicit \| inferred	Which use sites: 'all' (default), 'explicit' (only sites whose text names the symbol) or 'inferred' (only names whose type was INFERRED as it, e.g. 'p <- find(id)' for Product - one per name). The headline counts both either way.
`line`	integer	1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use `ek9_read_file`(lineNumbers:true).
`symbol`	string	A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there.

It also takes the arguments every tool takes.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 13 recorded are shown.

References shape

Request

{
  "file" : "MyRecord.ek9",
  "line" : 5
}

Response

{
  "declaredAt" : {
    "column" : 4,
    "file" : "MyRecord.ek9",
    "line" : 5
  },
  "fullyQualifiedName" : "com.example::MyRecord",
  "kind" : "TYPE",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "name" : "MyRecord",
  "referenceCount" : 1,
  "references" : [ {
    "column" : 4,
    "context" : "MyRecord",
    "explicit" : true,
    "file" : "MyRecord.ek9",
    "kind" : "declaration",
    "line" : 5,
    "symbol" : "MyRecord"
  } ],
  "status" : "ok",
  "summary" : {
...

Cut short here: 17 more lines. The whole recorded call.

References of a dispatcher entry point

Request

{
  "symbol" : "Painter.paint"
}

Response

{
  "declaredAt" : {
    "column" : 6,
    "file" : "Refs.ek9",
    "line" : 63
  },
  "fullyQualifiedName" : "com.example.inferred::paint",
  "kind" : "METHOD",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "name" : "paint",
  "referenceCount" : 1,
  "references" : [ {
    "column" : 6,
    "context" : "paint() as dispatcher",
    "explicit" : true,
    "file" : "Refs.ek9",
    "kind" : "declaration",
    "line" : 63,
    "symbol" : "paint"
  } ],
  "status" : "ok",
  "summary" : {
...

Cut short here: 17 more lines. The whole recorded call.

References builtin external

Request

{
  "column" : 26,
  "file" : "EnvUse.ek9",
  "line" : 8
}

Response

{
  "declaredAt" : null,
  "external" : true,
  "fullyQualifiedName" : "org.ek9.lang::get",
  "kind" : "METHOD",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "name" : "get",
  "referenceCount" : 1,
  "references" : [ {
    "column" : 25,
    "context" : "stdout.println(env.get(\"HOME\"))",
    "explicit" : true,
    "file" : "EnvUse.ek9",
    "inConstruct" : "demo",
    "kind" : "method_call",
    "line" : 8,
    "module" : "com.example",
    "symbol" : "get"
  } ],
  "status" : "ok",
  "summary" : {
    "byFile" : [ {
...

Cut short here: 18 more lines. The whole recorded call.