a2ui-project / a2ui-project/a2ui

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

Ouverte
#2,590 1 commentaire 0 réactions 1 personne assignée Réclamée par @josemontespg Voir sur GitHub
P2
Langage dominant
TypeScript
Étoiles
16.4k
Forks
1.3k
Merge moyen
2 j 13 h
PR mergées (30 j)
134

Description

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

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

The work involves packages like `web_core`, `angular`, `react`, and `samples`. Start by examining the `index.ts` entrypoints in these packages to understand the current wildcard exports. Use an AST tool like `ts-morph` to analyze the export graph. The goal is to replace `export *` statements with explicit named exports, ensuring no API surface changes by comparing snapshots before and after.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
typescript
Domaine
tooling
Type d'issue
Refactorisation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Active
Clarté
Clairement spécifiée
Accessibilité débutants
20/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.