code-yeongyu / code-yeongyu/oh-my-openagent
[Architecture] Resolving V8 initialization races by decoupling the internal shared barrel
- Dominant language
- TypeScript
- Stars
- 69.2k
- Forks
- 5.7k
- Avg merge
- 3h 2m
- Merged PRs (30d)
- 620
Description
### Context & Motivation
First of all, amazing work on the recent architectural updates! As the `oh-my-openagent` project scales with more complex asynchronous features (like background agents and loaders), the module resolution graph has naturally grown quite large.
While running some codebase graph analysis, I noticed that the centralized `src/shared/index.ts` barrel file is currently acting as a massive bottleneck, generating **91 circular dependency chains** across the `src/` directory.
While the `CONTRIBUTING.md` correctly encourages the Barrel Pattern for clean public APIs, utilizing it for *internal cross-module imports* (especially for low-level utilities like `logger` or `normalizeSDKResponse`) creates unintended consequences in Node.js/Bun.
### The Technical Impact
When a core file imports a basic utility from `../shared`, the engine inadvertently evaluates the entire high-level dependency tree bound to that barrel. This leads to:
1. **Temporal Dead Zones (TDZ) & Race Conditions**: Unpredictable module initialization order, which can cause subtle runtime bugs during CLI startup or Agent spawning.
2. **Brittle Test Suites**: Module mocks (in `bun test`) become highly unstable or leak because the barrel loads unexpected files into the test environment.
### Proposed Solution: Internal Leaf-First Decoupling
I propose a slight optimization to the current convention: **Keep barrels for external/public APIs, but enforce direct leaf-file imports for internal wiring.**
**Example:**
Instead of:
```typescript
import { log } from "../shared"
```
We optimize to:
```typescript
import { log } from "../shared/logger"
```
I have mapped the graph and ran an AST script to safely perform this decoupling across the ~180 affected files. The circular dependency count drops from 91 to 0 for these paths, and `bun run typecheck` remains pristine (0 errors).
👉 **I have opened a PR implementing this architecture below for your review.**
Contributor guide
Assessment
This issue has not been assessed yet.