ek9_organize_constants

Moves every `defines constant` declaration of one module into one block in one file (created when targetFile is new); answers status, edits[] (one INSERT + one DELETE per moved declaration) and conflicts[] (comments-in-block, module-ambiguous, target-file-ambiguous, pre-existing-duplicate-constant).

Category: Editor · Compare: NEW IDE surface — Refactor menu → "Organize Constants…". Nearest analogues are IntelliJ "Move Members…" (but constant-block-aware) and "Optimize Imports" (a whole-module tidy with no per-site decisions).

When to use it

'Gather this module's constants into one file' is one call with no arguments (module:'x' when several modules declare constants - the tool refuses to guess; targetFile to pick or create the file). Use it when a module's constants have fragmented across files (E11066: 3+ files; E11067: 2+ files with 10+ constants) or drifted into the wrong file.

When not to use it

Creating a NEW constant from a repeated literal in source (E11065) — use ek9_extract_constant. That authors a constant; this only relocates existing ones.
Promoting a local `name <- literal` to a module constant — use ek9_promote_to_constant.
Moving a class/record/trait/component/function between files — use ek9_move_construct (it handles those five genera only, not constants).
Deleting a donor left holding only its module header — use ek9_prune_empty_sources; this tool never deletes files.

Details

Semantics-preserving by construction: constants live in ModuleScope and codegen merges all module constants into one `_Constants` class, so no call site, `references` entry or generated byte changes. ONE module per call; a constant never crosses a module boundary; donor files are retained with their block excised and declarations keep donor source order. Comments in a block's declaration area are conflict 'comments-in-block' — mode:'hoist-comments' lifts them to the block header so consolidate then proceeds (a trailing same-line comment rides its line and never blocks); other conflict kinds are 'pre-existing-duplicate-constant', 'module-ambiguous' (several modules declare constants - supply module), 'target-file-ambiguous' (supply targetFile) and 'directive-bearing-declaration', while no-constants and already-consolidated are graceful no-ops, not errors.

Arguments

Argument	Type	What it is
`mode`	string: consolidate \| hoist-comments	consolidate (default) gathers every constant into one block; hoist-comments lifts comments out of each block's declaration area up to its header — the one-time mechanical repair that unblocks consolidate.
`module`	string	The exact module to organize. Default: the one module declaring constants; when several do, the call is conflicts[{kind:'module-ambiguous', modules:[...]}] until you name one.
`targetFile`	string	Workspace-relative path of the file that will hold the consolidated block. Three cases, all supported: (1) a source file of the resolved module that already has a `defines constant` block; (2) one with no such block yet — a block is created at the canonical position; (3) a path that DOES NOT EXIST — the file is created as a source file of this module (shebang + `defines module` + //EOF) with the consolidated block in it. Case (3) is the dedicated-constants-file outcome E11066's guidance recommends, so name e.g. 'myModuleConstants.ek9' and this one call does it; no separate `ek9_write_file` step is needed. Nothing is written on dryRun. Default: the file holding the block with the most declarations. Rejected for hoist-comments.

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

Organize constants noop rerun

Request

{ }

Response

{
  "conflicts" : [ ],
  "edits" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 0,
    "lineCount" : 0,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "applied",
  "summary" : "All 5 constants already consolidated in rich.ek9 — nothing to move",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : true
}

Organize constants module ambiguous

Request

{
  "dryRun" : true
}

Response

{
  "conflicts" : [ {
    "kind" : "module-ambiguous",
    "message" : "2 modules declare constants (organize.other, organize.probe) - pass module:'<name>' to say which one to organize.",
    "modules" : [ "organize.other", "organize.probe" ]
  } ],
  "edits" : [ ],
  "meta" : {
    "serverMs" : "<timing>"
  },
  "risk" : {
    "crossesModuleBoundary" : false,
    "estimatedSeverity" : "trivial",
    "fileCount" : 0,
    "lineCount" : 0,
    "touchesPublicApi" : false,
    "touchesTests" : false
  },
  "status" : "conflicts",
  "summary" : "Several modules declare constants - pass module",
  "workspaceHash" : "<workspace-hash>",
  "wouldBeDiagnostics" : [ ],
  "written" : false
}

Organize constants apply

Request

{
  "terse" : true
}

Response

{
  "conflicts" : [ ],
  "edits" : [ {
    "endLine" : 4,
    "file" : "donorOne.ek9",
    "startLine" : 4,
    "type" : "delete"
  }, {
    "endLine" : 5,
    "file" : "donorOne.ek9",
    "startLine" : 5,
    "type" : "delete"
  }, {
    "endLine" : 4,
    "file" : "donorTwo.ek9",
    "startLine" : 4,
    "type" : "delete"
  }, {
    "endLine" : 5,
    "file" : "donorTwo.ek9",
    "startLine" : 5,
    "type" : "delete"
  }, {
    "endLine" : 8,
...

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

When to use it

When not to use it

Details

Arguments

Recorded calls

Organize constants noop rerun

Organize constants module ambiguous

Organize constants apply

See also