a2ui-project / a2ui-project/a2ui
[Refactor] Replace wildcard barrel exports (`export *`) with explicit named exports across TypeScript packages
- Vorherrschende Sprache
- TypeScript
- Sterne
- 16.4k
- Forks
- 1.3k
- Ø Merge
- 2 T. 13 Std.
- Gemergte PRs (30 T.)
- 134
Beschreibung
## 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.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.