Skip to content

refactor: organize extension and webview code by topic - #1134

Merged
EhabY merged 2 commits into
mainfrom
refactor/remove-util-modules
Oct 10, 2026
Merged

refactor: organize extension and webview code by topic#1134
EhabY merged 2 commits into
mainfrom
refactor/remove-util-modules

Conversation

@EhabY

@EhabY EhabY commented Oct 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Follow-up to the review on #1133. This removes src/util.ts, src/util/ and src/core/, names webview modules by topic, and writes the layout rules down in CODE_STRUCTURE.md, which AGENTS.md now links to. There are no behavior changes.

How to review

Go commit by commit. Commits are grouped by area, so each could also land as its own PR:

  1. Extension: move modules. Renames only, with import paths updated. Covers util and core/ modules, the panel rename and test moves.
  2. Extension: split and merge by topic. The real review: functions move between the files renamed in commit 1.
  3. Webviews. Topic names for utils modules, the speedtest formatter split, and tests that mirror their source.
  4. Docs. CODE_STRUCTURE.md, linked from AGENTS.md and CONTRIBUTING.md.

Layout rules

The full list is in CODE_STRUCTURE.md. The main ones:

  • Colocate. A helper with one consumer lives in that consumer's file (Kent C. Dodds).
  • Group by topic. Shared helpers go in topic modules with several functions each, the way VS Code does in base/common. No utils or helpers files.
  • Respect runtime boundaries. The extension host and webviews talk only through the IPC contracts in @repo/shared, which stays free of Node, DOM and vscode. @repo/ui depends on no other workspace package, so it can be split out later (Electron process model, VS Code source organization).
  • Mirror tests. Every test mirrors its source path, in both the extension and the webview packages.

Where things went

  • Extension: common/ (fs, strings, url), ui/, api/models, cli/, storage/, vscode/, and container.ts next to extension.ts (the composition root). Single-use helpers moved into the file that uses them.
  • Webviews:
    • utils modules are renamed by topic: shared/{error/toError, netcheck/severity, tasks/status}, plus speedtest/{chartGeometry, format}.
    • tasks/src/utils/* moves to the package root, and useTaskMenuItems moves into hooks/.
    • webview-shared tests move to test/webview/webview-shared/.

Follow-ups

Testing

Each commit passes typecheck, lint, format check and unit tests (2780 passed / 6 skipped, the same as main). pnpm build passes.

🤖 Generated with Claude Code

@EhabY
EhabY force-pushed the refactor/remove-util-modules branch from d1985b6 to 62f4049 Compare October 5, 2026 11:41
@EhabY EhabY changed the title refactor: replace util modules with topic-named modules refactor: replace util and core with topic modules Oct 5, 2026
@EhabY EhabY mentioned this pull request Oct 5, 2026
Open
@EhabY EhabY changed the title refactor: replace util and core with topic modules refactor: organize extension and webview code by topic Oct 5, 2026
@EhabY
EhabY force-pushed the refactor/remove-util-modules branch 2 times, most recently from 9af3d07 to 5773fb0 Compare October 5, 2026 12:36
@EhabY EhabY mentioned this pull request Oct 5, 2026
Merged
@EhabY
EhabY requested a review from aslilac October 6, 2026 11:17
aslilac
aslilac approved these changes Oct 6, 2026
View reviewed changes

@aslilac aslilac left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

huge fan of this kind of reorganization. I think people are often way to hesitant to do it, and I think it still matters in a world of agents for making sure they (and humans) can actually find the code they're looking for. otherwise we get the same helper functions implemented 18 times in different files. :)

@EhabY
EhabY force-pushed the refactor/remove-util-modules branch 2 times, most recently from 6cd1b2d to 17b5714 Compare October 9, 2026 14:42
EhabY added 2 commits October 10, 2026 18:48
@EhabY
refactor: name modules by topic and document the code structure
6daf51c 
Replace the util and grab-bag modules with topic-named modules, and write
the layout rules down in CODE_STRUCTURE.md.

Extension:
- Move each util module to the module that takes most of its code (for
  example `util/fs` to `common/fs`, `api/utils` to `api/httpAgent`,
  `core/cliUtils` to `cli/cliBinary`). `core/` splits into `cli/`,
  `storage/` and `vscode/`; `container.ts` moves next to `extension.ts`,
  and `vscodeProposed.ts` becomes `vscode/proposed.ts`.
- Split grab-bag modules by topic: `common/fs`, `common/strings`,
  `common/url`, `api/models`, `error/abort`, `error/normalize`,
  `logging/ids`, `oauth/tokens`, and `sessionId` in `telemetry/ids`.
- Move single-consumer helpers into their consumer, and drop the unused
  `LogSources` re-export.

Webviews:
- Rename `utils` modules after their topic (`shared/error/toError`,
  `shared/netcheck/severity`, `shared/tasks/status`,
  `speedtest/chartGeometry`, `speedtest/format`), lift `tasks/src/utils/*`
  to the package root, and move `useTaskMenuItems` into `tasks/src/hooks/`.

Tests move to mirror their source path.

CODE_STRUCTURE.md covers the runtime boundary and one-way package
dependencies, `@repo/ui` as a standalone library, where new code goes,
topic names instead of `utils`/`helpers`, file naming, and test placement.
It describes how to decide rather than listing folders, so adding a folder
or package needs no doc change.
@EhabY
chore: clean up root files, tooling config, and agent docs
4f95c79 
Root files:
- Fold usage.md into the README and move demo.gif into media/. The README
  links it by relative path, which vsce rewrites to the default branch.
- Move esbuild.mjs to scripts/ and the integration test config to
  test/integration/.
- Replace .vscodeignore with a package.json "files" allowlist; vsce ls
  produces the same file list.
- Merge .oxlintrc.react.jsonc into .oxlintrc.jsonc, listing the typescript
  and oxc plugins the extended file pulled in, so the resolved config is
  identical.
- Remove the Prettier leftovers; Oxfmt formats every file type with its own
  bundled Prettier.
- Keep the ESLint cache in node_modules and trim .gitignore.

Dependencies and environment:
- Drop devDependencies nothing loads since the Oxlint migration.
- Update the Nix flake: pin nixpkgs, use Node 24 and nixpkgs' pnpm, and stop
  pnpm downloading a prebuilt binary that cannot run on NixOS.
- Make the VS Code launch config build before running the extension.

Docs:
- Restructure AGENTS.md after coder/coder: a short root file that routes to
  topic guides in docs/ (code structure, architecture, testing, tooling) and
  packages/AGENTS.md for webviews, kept short since agents load them on
  every task. CONTRIBUTING.md keeps setup, PR and review guidance, and
  releasing.
- Adopt the coder/coder rules that apply here, plus Testing Library's own
  testing guidance, and forbid em and en dashes as punctuation.
- Match the generated SSH config example to the current output, and drop
  the requirement to close VS Code before integration tests.
@EhabY
EhabY force-pushed the refactor/remove-util-modules branch from 17b5714 to 4f95c79 Compare October 10, 2026 15:49
@EhabY
EhabY merged commit 01093dc into main Oct 10, 2026
12 of 13 checks passed
@EhabY
EhabY deleted the refactor/remove-util-modules branch October 10, 2026 15:51
This was referenced Oct 10, 2026
Open
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aslilac aslilac aslilac approved these changes

Assignees

@EhabY EhabY

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@EhabY @aslilac