ek9_sync_references

Rewrites one file's 'references' block - adding the module::Name entry for each cross-module symbol the file uses but has not declared (E50001/E50010) and deleting each entry nothing uses - and answers the editor envelope: status (applied | ready | conflicts | error), written, edits[] and summary ('Added N and removed M reference(s)').

Category: Editor · Compare: Optimize Imports (IntelliJ) / Organize Imports (VS Code)

When to use it

'Fix this file's references block' (the EK9 Organize Imports) is one call: {file:'x.ek9'} adds every missing cross-module reference and removes every unused one.

When not to use it

• You only want to KNOW which symbols are unresolved without rewriting - use ek9_query_diagnostics.
• You want to just reformat whitespace/indent, not change references semantics — use ek9_format.
• You're moving a construct between modules (it rewrites references as part of the move) — use ek9_move_construct (mode=cross-module).
• You want to consolidate a shared reference set across many files into one shared file — that is workspace-wide, not this single-file tool.

Details

Entries are symbol-level (module.path::Identifier) — no module wildcards; disable addMissing or removeUnused for a surgical one-sided sync. Add-detection is compiler-driven (file-scoped scratch compile, iterated to a fixpoint since EK9 surfaces unresolved names across several phases). A name resolving to more than one module is surfaced as status:conflicts (kind auto-added-reference-creates-ambiguity — fully-qualify the use site, then retry) rather than guessed; a stale entry whose symbol no longer exists is simply removed as unused.

Arguments

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 4 recorded are shown.

Both toggles false error

Request

{
  "addMissing" : false,
  "file" : "uses.ek9",
  "removeUnused" : false
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "addMissing and removeUnused cannot both be false — nothing to sync"
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "addMissing and removeUnused cannot both be false — nothing to sync",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Added ref sorted before existing

Request

{
  "dryRun" : true,
  "file" : "uses.ek9"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ {
    "after" : "    probe.defs::Alpha",
    "endLine" : 5,
    "file" : "uses.ek9",
    "startLine" : 5,
    "type" : "insert"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 1,
    "lineCount" : 1,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "ready",
  "summary" : "Added 1 reference(s) in uses.ek9",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
...

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

Add missing cross module

Request

{
  "dryRun" : true,
  "file" : "uses.ek9"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ {
    "after" : "  references\n    probe.defs::Widget\n",
    "endLine" : 4,
    "file" : "uses.ek9",
    "startLine" : 4,
    "type" : "insert"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 1,
    "lineCount" : 1,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "ready",
  "summary" : "Added 1 reference(s) in uses.ek9",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
...

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

See also

• Show me in the IDE: Sync References