a2ui-project / a2ui-project/a2ui

[Refactor] Replace wildcard barrel exports (`export *`) with explicit named exports across TypeScript packages

Đang mở
#2,590 1 bình luận 0 reaction 1 người được giao Được @josemontespg nhận Xem trên GitHub
P2
Ngôn ngữ chính
TypeScript
Star
16.4k
Fork
1.3k
Merge trung bình
2 ngày 13 giờ
Pull request đã merge (30 ngày)
134

Mô tả

## Context and Rationale

Currently, many of our TypeScript packages (including `web_core`, `angular`, `react`, and `samples`) rely on wildcard barrel exports (e.g., `export * from './module';`) to expose their public API surface. While convenient, this pattern introduces maintainability and compilation issues:

1. **Silent Duplicate Identifiers (TS2300):** Wildcard exports natively swallow overlapping identifier names silently. If two modules export a type with the same name, the wildcard export will mask the collision, which can lead to unpredictable type resolution for consumers.
2. **API Visibility:** Explicit exports provide a clear, trackable API surface area directly in the entrypoint file (`index.ts`). It makes it significantly easier to review API changes in PRs.

*Note: This refactor was briefly explored (see [PR #2587](https://github.com/a2ui-project/a2ui/pull/2587)) but intentionally postponed until after the `v1_0` renderer directory restructuring is merged to avoid massive merge conflicts.*

## Implementation Plan

Once the `v1_0` renderer codebase restructure is merged into `main`, this refactor should be executed systematically to guarantee zero breakage to the public API.

### Recommended Execution Steps:

*(See [this gist](https://gist.github.com/josemontespg/6cf911059b40e3c8540bc86347301c36) for a detailed reference to our previous refactoring plan).*

1. **AST-Driven Extraction:**
Use an AST manipulation tool (like `ts-morph`) to programmatically read all `index.ts` entrypoints, parse the wildcard exports, and walk the import graph to extract the explicit identifier names from the source modules.

2. **Type-Aware Emission:**
The extraction script must differentiate between value declarations (classes, functions, consts) and type declarations (interfaces, type aliases). It must format the new exports to comply with `--isolatedModules` (e.g., converting `export * from './types'` to `export type { Config, State } from './types'`).

3. **Collision Deduplication:**
The script must maintain a registry of exported identifiers per entrypoint. If a duplicate identifier is encountered (which was previously swallowed by the wildcard), the script should deduplicate it (typically favoring the first exported instance) to prevent `TS2300` errors.

4. **API Parity Verification:**
Before making any changes, run an AST script to generate a JSON snapshot of the exact public API surface (all exported names per package). After the refactor, generate a second snapshot and diff them. The diff must be exactly zero to guarantee that no exports were accidentally dropped or exposed.

5. **Formatting Compliance:**
Because AST tools often generate extremely long single-line export statements that fail CI linting, ensure that the project's formatting suite (`./scripts/fix_format.sh` and Prettier) is run locally before committing.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.