ek9_change_signature

Rewrites the declaration and EVERY call site atomically (add / remove / reorder parameters, change the return type, toggle 'as pure'); answers status, edits[] and summary with the call-site count, a blocking call site as conflicts[] (callsite-incompatible-with-new-signature).

Category: Editor · Compare: Refactor → Change Signature (IntelliJ)

When to use it

'Add a parameter to Order.total and fix every caller' is one call with symbol:'Order.total' and mutations:[{kind:'add-parameter', parameter:{...}}]. A constructor is 'Order.Order' - its 'Order(...)' calls are updated the same way.

When not to use it

Renaming the method - use ek9_rename_symbol; removing it entirely - use ek9_safe_delete; adding a brand-new method - use ek9_add_method.
Extracting a code block into a NEW method - use ek9_extract_method.
Promoting an in-body expression to a parameter - use ek9_introduce_parameter.
Operators (fixed contracts) - use ek9_safe_delete + ek9_add_operator; a brand-new constructor beside the existing ones - use ek9_add_constructor; a purity COMPILE ERROR to reconcile - use ek9_fix_purity_contract.

Details

EK9 has NO default parameter values, so add-parameter REQUIRES valueForExistingCalls (an EK9 expression injected at every existing call site) and injects a 'require <name>?' guard + //AI: block (E08091 bans unused params) unless the target is an override. When the post-change count reaches 4+, all positional call sites auto-rewrite to named-argument form (name: value) per E11062. Targeting a leaf override resolves UP to its root contract and cascades the whole family (resolved-to-contract advisory); semantic cascades (purity E05150/E05160, return-type incompatibility, override cascades) surface as would-fail from the scratch compile in V1, not structured conflict kinds.

Arguments

Argument	Type	Required	What it is
`column`	integer		IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead.
`file`	string		The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site.
`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).
`mutations`	array of any	yes	One or more mutations applied atomically, in order. Each: {kind: 'add-parameter' (+ parameter: {name, type, position?, valueForExistingCalls: the expression every existing call passes - REQUIRED whenever anything calls it, EK9 has no default parameter values}), 'remove-parameter' (+ removeParameterName, + optional dropCallSiteArguments: true to drop the argument expression at every call site — without it live call sites block the removal), 'reorder-parameters' (+ newParameterOrder: [names]), 'change-return-type' (+ newReturnType — null removes the return clause; OMIT the mutation to keep the return type), 'change-purity' (+ pure: true \| false)}. position omitted = append.
`symbol`	string	yes	The method or function - 'Order.total' or a bare function name finds its file and declaration workspace-wide; 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 38 recorded are shown.

Change signature bad permutation error

Request

{
  "column" : 5,
  "file" : "main.ek9",
  "line" : 13,
  "mutations" : [ {
    "kind" : "reorder-parameters",
    "newParameterOrder" : [ "first" ]
  } ]
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "newParameterOrder must be a permutation of existing parameter names — missing: [second], extra: []"
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "newParameterOrder must be a permutation of existing parameter names — missing: [second], extra: []",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Program not offered a constructor

Request

{
  "file" : "task.ek9",
  "mutations" : [ {
    "kind" : "change-return-type",
    "newReturnType" : "Integer"
  } ],
  "symbol" : "Main"
}

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "error" : {
    "message" : "No method or function at: task.ek9:23 - that line declares the program 'Main': name the member as symbol:'Main.<method>'"
  },
  "meta" : {
    "serverMs" : "<timing>"
  },
  "status" : "error",
  "summary" : "No method or function at: task.ek9:23 - that line declares the program 'Main': name the member as symbol:'Main.<method>'",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Change signature add pure apply

Request

{
  "column" : 5,
  "file" : "main.ek9",
  "line" : 18,
  "mutations" : [ {
    "kind" : "change-purity",
    "purityChange" : "add-pure"
  } ]
}

Response

{
  "conflicts" : [ ],
  "edits" : [ {
    "after" : "    helper() as pure\n      -> inputText as String\n      <- result as String: inputText",
    "before" : "    helper()\n      -> inputText as String\n      <- result as String: inputText",
    "endLine" : 20,
    "file" : "main.ek9",
    "startLine" : 18,
    "type" : "replace"
  } ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "high",
    "fileCount" : 1,
    "lineCount" : 3,
    "touchesPublicApi" : true,
    "touchesTests" : false
  },
  "status" : "applied",
  "summary" : "Changed function helper: add 'as pure' (0 call sites updated)",
  "workspaceHash" : "<workspace-hash>",
...

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

When to use it

When not to use it

Details

Arguments

Recorded calls

Change signature bad permutation error

Program not offered a constructor

Change signature add pure apply

See also