Organize imports and reorganize module-level code into canonical bands - #928
Open
chughtapan wants to merge 5 commits into
Open
Organize imports and reorganize module-level code into canonical bands#928chughtapan wants to merge 5 commits into
chughtapan wants to merge 5 commits into
Conversation
Top-down file order requires a helper to sit below its first caller. A `const` arrow cannot: it stays in the temporal dead zone until evaluated, so a call above it throws. Function declarations hoist, which makes the placement legal. Converts the 177 module-level, non-exported arrow helpers that carry no type annotation and never reference `this`. Three are left as arrows: one whose annotation contextually types its parameters, and two whose bodies reference `this`. Mechanical, via scripts/codemods/arrow-to-function.mjs. Edits are computed as text ranges and applied back-to-front, so comments and formatting are untouched; oxfmt normalizes the result. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HY7ipPDdGVENSPVe51UcJe
Files read top-down: imports, declarations (types, SCREAMING_CASE constants, error classes), primary exports, implementation. Within the implementation band, each helper sits below its first caller. Only types (erased) and function declarations (hoisted) move. A file whose `const`/`class` statements would change relative order carries initialization-order risk that cannot be checked mechanically, so it is reported rather than rewritten — 82 files, including every file over ~800 lines. Three safeguards, each added after the codemod got it wrong: - the rewrite asserts it is a permutation of the original statements before writing, so an unclassified statement kind cannot be dropped; - blank-line grouping is carried per statement, so packed runs stay packed; - a leading `@file` block is pinned above the body, since it documents the module rather than the statement it precedes. 53 files, 447 statements moved, net -2 lines. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HY7ipPDdGVENSPVe51UcJe
The six methods that owned the agent id → name map touched nothing else on the service except the RPC sender, so they move to a collaborator that carries its own Ref and takes the sender as its only dependency. `fake-service` reached the map through `Reflect.get(this, "agentNamesRef")` — a test double coupled to a private field. It now goes through the cache's own `cache()` surface, so the seam is the collaborator's API rather than the service's internals. Verified: nx run-many -t build, -t lint, -t test all green (761 tests). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HY7ipPDdGVENSPVe51UcJe
Adds eslint-plugin-perfectionist, limited to axes where declaration order is arbitrary: named imports and exports, heritage clauses, variable declarations, array includes, sets, and maps. Autofixed across the tree. Deliberately excluded, with the reason recorded beside the config: - sort-imports / sort-exports — both treat a module's `@file` docblock as trivia belonging to the statement below it, so sorting hoists a statement over the block and strands the file's documentation between imports, which `jsdoc/require-file-overview` then rejects. `partitionByComment` fixes it for imports but not exports. Enabling these needs a one-time pass moving every docblock above all imports first. - sort-modules, sort-classes — fight the band layout and the stepdown rule. - sort-union-types, sort-enums — a union like `LeaseState` reads as a lifecycle; alphabetizing destroys it. - sort-interfaces, sort-object-types — wire shapes whose field order flows into the generated protocol docs. - sort-objects — 2586 sites, mixing arbitrary config with semantic ordering; not separable without per-site review. Verified: nx run-many -t build, -t lint, -t test all green (761 tests). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HY7ipPDdGVENSPVe51UcJe
The earlier note blamed `@file` docblock stranding. That is real but solvable — `partitionByComment: true` anchors every block, verified on the barrels that failed before. The actual blocker is an import cycle. `@moltzap/protocol` has `conversation` <-> `task`, so import order decides module evaluation order and is load-bearing: `task/tasks.ts` calls `conversationSchema()` at module scope, which resolves only because `#conversation` is imported after `#transport`. Alphabetizing moves it first and the call throws `conversationSchema is not a function` at import time — 15 test files, in protocol and server-core. Import order is therefore not a meaning-free axis in this codebase, which is the premise the whole sorting effort rested on. Breaking the cycle (relocating `TaskId` / `TaskNotFoundError` to a module both halves can depend on) is a protocol design change, not a lint change, so the rules stay off and the reason is recorded where someone would try again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HY7ipPDdGVENSPVe51UcJe
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR applies a systematic file organization migration across the codebase, reorganizing imports and module-level declarations into canonical "bands" (logical sections) and converting arrow function helpers into hoisted function declarations.
Key Changes
SCREAMING_CASEconstants, error classesconst f = (...) => ...helpers intofunction f(...)declarations, which hoist and improve code organizationarrow-to-function.mjs: Step 1 - converts arrow functions to declarationsreorder-bands.mjs: Step 2 - moves declarations into canonical bands and orders implementation by first callhoist-module-docblock.mjs: Moves module docblocks above imports when neededNotable Implementation Details
Files Modified
@moltzap/protocol,@moltzap/server,@moltzap/client,@moltzap/testbednanoclaw-channel,openclaw-channelhttps://claude.ai/code/session_01HY7ipPDdGVENSPVe51UcJe