a2ui-project / a2ui-project/a2ui

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

Abierto
#2,590 1 comentario 0 reacciones 1 asignado Reclamado por @josemontespg Ver en GitHub
P2
Lenguaje dominante
TypeScript
Estrellas
16.4k
Forks
1.3k
Merge medio
2 d 13 h
PR fusionados (30 d)
134

Descripción

## 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.

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.