a2ui-project / a2ui-project/a2ui

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

Open
#2,590 1 comment 0 reactions 1 assignee Claimed by @josemontespg View on GitHub
P2
Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
2d 13h
Merged PRs (30d)
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.

Contributor guide

Open the contributing guide

Research direction

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.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.