Skip to content

[typespec-ts] wip split emitter into adapter / codemodel / codegen#3981

Draft
maorleger wants to merge 35 commits into
Azure:mainfrom
maorleger:squad-rewrite
Draft

[typespec-ts] wip split emitter into adapter / codemodel / codegen#3981
maorleger wants to merge 35 commits into
Azure:mainfrom
maorleger:squad-rewrite

Conversation

@maorleger
Copy link
Copy Markdown
Member

@maorleger maorleger commented May 18, 2026 •
edited
Loading

This is the refactor I've wanted for the TypeSpec TS modular emitter for a while: make it boring.

The core problem I noticed was that the old path was reading TCGC types, shaping emitter state, and rendering with ts-morph all mixed together across src/modular/. That works until it doesn't. It makes it much harder to reason about boundaries, test the adaptation layer directly, or move code around without accidentally dragging TCGC assumptions everywhere. The real symptoms show up as hard-to-trace bugs that belong in one layer but live in another.

What I wanted from this refactor:

  • Enforce a three-layer pipeline: TCGC input → adapter (converts to pure IR) → code model (pure data, no side effects) → codegen (renders with ts-morph)
  • Keep the swap in-place so we validate against the existing emitter behavior the entire time instead of incubating a parallel implementation that might diverge
  • Make it obvious where a bug belongs: TCGC adaptation, pure IR shaping, or ts-morph rendering
  • Make the eventual cleanup / deletion story less painful once the dust settles

This PR builds off of #3970 (the seed POC for the separation). The in-place modular refactor landed in stages 0-6, and I ran the entire suite against real Azure specs to shake out customer-found issues. Stages 0-6 are now wired: src/tcgcadapter/adapter.ts is the only place that imports TCGC directly and adapts it into the pure IR in src/codemodel/index.ts. From there, src/codegen/ owns the ts-morph rendering for clients, operations, classical clients/operations, models, enums, unions, response types, API options, LRO helpers, and index files. In other words, "what the SDK is" stays separate from "how we print it".

I also started a north-star package at packages/typespec-ts-pristine/ (commits 6c0f156 through 03abed9, 9 slices in). This imagines what we'd write today knowing what we know now — a clean-room emitter with zero internal monorepo dependencies (no rlc-common, no typespec-ts), liftable with a cp -r. It has a comparator script that validates output equivalence. Early demo results: spread fixture matches at 95.2%, overloads_modular at 85.7%. See packages/typespec-ts-pristine/docs/DESIGN.md for the architecture blueprint.

Worth flagging: the end goal isn't to land this rewrite in autorest.typescript. The emitter is being migrated as-is into typespec-azure, and the real plan is to do this refactor there once the migration lands. This PR is exploratory — it proves the shape works against real fixtures and gets the boring pipeline working so we know what we're committing to.

I could have hidden this behind a feature flag or kept it additive for longer; however, I'd rather do the swap in place and keep one source of truth if possible. The migration is still very much WIP.

Still not done in this PR:

  • ContextManager is still an ambient singleton instead of explicit data flow
  • the adapter still leans on a few helpers from src/modular/helpers/
  • there is still no dedicated src/tcgcadapter/naming.ts module yet

Validation on this branch is green:

  • pnpm build
  • 662 unit tests passing
  • modular + azure-modular integration passing
  • smoke passing

Scope-wise this is 25 files under packages/typespec-ts/ plus a tiny .gitignore housekeeping change for local team-state files. The last commit is just that housekeeping and not part of the architectural story.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

maorleger and others added 14 commits May 18, 2026 17:25
@maorleger
Scribe: Merge Ripley staged refactor plan and update cross-agent history
959980e 
Tasks executed:
1. ✅ Decisions archive: No archival needed (decisions.md < 20KB threshold)
2. ✅ Decision inbox: Merged ripley-staged-refactor-plan.md + copilot-directive into decisions.md
   - Summary of 9-stage pipeline refactor (stages 1–9, stage 10 dropped)
   - Key decisions: swap-in-place, adapter testing focus, readability-first organization
   - Directives: skip lint guard, focus adapter tests, skip package separation
3. ✅ Orchestration log: Created 2026-05-15T2238Z-ripley.md (not git-tracked per .gitignore)
4. ✅ Session log: Created 2026-05-15T2238Z-refactor-plan.md (not git-tracked per .gitignore)
5. ✅ Cross-agent history: Appended Ripley plan summary to dallas/history.md and parker/history.md
6. ✅ History summarization: All history.md < 15KB (no summarization needed)
7. ✅ Git commit: Staged 3 files (decisions.md, dallas/history.md, parker/history.md)
8. ✅ Health report: decisions.md 0→1710 bytes, inbox count 2→0 (after merge)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts): wire client context through new three-layer pipeli…
696359c 
…ne (Stage 1)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
test(typespec-ts): add operation adapter unit tests (Stage 2)
0ce15dd 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts): expand IR with operation types and adapter functio…
0d8d3ba 
…ns (Stage 2)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
test(typespec-ts): add model/enum/union adapter unit tests (Stage 3)
4f8c8cb 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts): expand IR with model, enum, and union types (Stage 3)
80fbad6 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
test(typespec-ts): activate model/enum/union adapter tests (Stage 3)
6170bef 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
Scribe: Stabilize Stage 3 build — fix incomplete adapter implementation
36fa112 
- Fix Stage 3 adapter: add missing isRLCMultiEndpoint import
- Fix child TSClient construction: add allowOptionalSubscriptionId and usesNamespacedContextType properties
- Rewrite adaptFunctionDeclaration for safe handling of OptionalKind types from ts-morph
- Update adapter test expectations for new IR properties (TSClient 16→18, TSMethod 9→17)
- Validate: build ✅, unit tests ✅ (662/662 passing), format ✅
- Document session: .squad/log/2026-05-16T0107Z-stage3-scribe-fixes.md
- Update decisions.md: Stage 2/3 completion notes

Stage 3 now unblocked. Parker ready to implement model/enum/union adapters.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts): wire operations through new three-layer pipeline (…
1636722 
…Stage 4)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts): migrate remaining file categories through new pipe…
233bfea 
…line (Stage 5)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts): wire models and response types through new pipelin…
62013ec 
…e (Stage 6a)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
fix(typespec-ts): fix smoke regressions — LRO spread, duplicate impor…
3a8245f 
…ts, serializer placeholders

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
fix(typespec-ts): fix client-initialization syntax error in azure-mod…
66c0f95 
…ular codegen

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
chore: gitignore local squad/team scratch files
6efd15c 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger maorleger changed the title Squad rewrite WIP: simplify emitter architecture May 18, 2026
@maorleger maorleger changed the title WIP: simplify emitter architecture [typespec-ts] wip split emitter into adapter / codemodel / codegen May 18, 2026
maorleger and others added 8 commits May 18, 2026 22:40
@maorleger
docs(typespec-ts): add ARCHITECTURE.md
b9a628b 
High-level architecture map for the typespec-ts emitter:  entry,
RLC vs Modular split, the three-layer TCGC adapter -> code model -> codegen
pipeline, framework/reference system, two end-to-end flows, and current
known follow-ups.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
Surface modular deprecation docs
d4b543a 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
Revert "Surface modular deprecation docs"
4382f14 
This reverts commit d4b543a.
@maorleger
fix(typespec-ts): include top-level api/** barrels in root index emis…
d24c617 
…sion

package.json continued to advertise ./api/<resource> subpath exports, but the rewritten root index only re-exported ./api/index.js. That left the source graph unable to reach those barrels, so the dist subpath files and root OptionalParams re-exports were never produced during build.

Restore the missing top-level api/** recursion in root index emission so the producer once again reaches every generated api subbarrel instead of trying to clean things up downstream.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
fix(typespec-ts): preserve optional api-version on client context
e35c324 
The rewritten client-context renderer was treating every api-version parameter as required based on isApiVersion alone, even when the adapter had already recorded a client default and left the parameter optional. That changed generated *Context interfaces from apiVersion?: string to apiVersion: string for defaulted clients.

Make requiredness follow the adapted TSClientParameter metadata instead of the api-version marker, and lock it in with a modular unit test that renders the new pipeline's client context for a versioned client with a defaulted api-version.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
fix(typespec-ts): emit models from filtered IR, drop TCGC import from…
e8b5a80 
… models renderer

The new pipeline's models renderer was still walking the legacy global emit queue, so it bypassed the adapter's filtered TSCodeModel.models/enums/unions set and reintroduced paging result types like *ListResult onto the public surface.

Switch file selection to the filtered IR and look raw sdk types up only for the legacy declaration/serializer helpers that are still shared with src/modular/emitModels.ts. The production path remains src/codegen/models.ts; the legacy file stays as a rendering helper while this removes the direct TCGC dependency from the codegen layer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
style(typespec-ts): format rewrite regression fixes
56aa9c5 
Apply formatter output for the client-context and model-renderer regression fixes after re-running build and unit validation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
fix(codegen/models): emit array/dict serializer helpers to resolve B8…
9a21858 
… placeholders

The new filtered-IR renderer in src/codegen/models.ts only walked
codeModel.models/enums/unions and skipped array/dict helper types from the
emitQueue. The serializer builders (buildSerializerFunction.ts,
buildDeserializerFunction.ts) still emit refkey(type, 'serializer') /
refkey(type, 'deserializer') references for those helpers. With no matching
declaration registered, the binder left __PLACEHOLDER_*__ tokens unresolved —
causing 26 TS2304 errors in the SCVMM and NetworkAnalytics repros.

Strategy A: walk emitQueue entries of kind 'array'/'dict' and call emitType()
for each, mirroring what the legacy emitTypes() in emitModels.ts did. This
registers the serializer/deserializer refkeys so the binder can substitute them.

A TODO comment and .squad/decisions/inbox/dallas-models-helpers.md document
the follow-up to migrate these helper types into TSCodeModel IR, removing the
emitQueue side-channel dependency from the codegen layer.

Validated:
- pnpm build: clean
- npm run unit-test (typespec-ts): 664/664 passed
- NetworkAnalytics.Management regen: zero __PLACEHOLDER_ matches, zero TS2304

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
maorleger and others added 4 commits May 20, 2026 21:18
@maorleger
[typespec-ts] migrate model helper types into IR
b068e3f 
Implement Strategy B for modular model helpers by adapting array, dict, and named nullable wrapper types into TSCodeModel.helperTypes and consuming that IR from codegen/models.ts instead of the legacy emitQueue patch.

This keeps helper registration in the adapter, removes the dead Strategy A loop from the renderer, and leaves the extensible-enum follow-up (U1) explicitly scoped to adaptEnums.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
[typespec-ts] fix extensible enum model emission
44dbf42 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
chore: untrack stray .squad/ files
30a8e08 
These two files were committed before .gitignore caught .squad/. Untracking
so the squad-rewrite branch stays free of squad meta-files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): scaffold north-star emitter package
6c0f156 
Three-layer pipeline architecture (adapter → code model → renderer) following
the proven patterns from typespec-rust and autorest.go. Contains:

- Design document (docs/DESIGN.md) with full surface inventory and IR contract
- Code model IR types (src/codemodel/) — pure data, no TCGC imports
- Adapter stub (src/tcgcadapter/) — TCGC boundary, only layer that imports TCGC
- Renderer stub (src/codegen/) — consumes IR only, one function per file kind
- Comparator scaffold (src/comparator/) — diff tool interface for validation
- Package infrastructure (package.json, tsconfig.json, README.md)

All stubs compile cleanly. No implementation yet — architecture only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
maorleger and others added 9 commits May 28, 2026 19:40
@maorleger
feat(typespec-ts-pristine): first vertical slice — adapt + renderMode…
0d98c08 
…ls + comparator on spread

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slice 2 — serializer IR + tightened model…
9baa130 
… selection

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slice 3 — emitter registration, barrels, …
db529fc 
…SDK metadata

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slices 4+8 — client context + logger
a334037 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slice 5 — operations + options
d908a98 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slice 6 — classical client class
f1606e4 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slice 7 — barrel files, spread structural…
d7e90a0 
…ly complete

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
feat(typespec-ts-pristine): slice 9 — second fixture validation, over…
03abed9 
…loads_modular

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@maorleger
docs: editorial pass
e799065 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@joheredi joheredi Awaiting requested review from joheredi joheredi will be requested when the pull request is marked ready for review joheredi is a code owner

@qiaozha qiaozha Awaiting requested review from qiaozha qiaozha will be requested when the pull request is marked ready for review qiaozha is a code owner

@MaryGao MaryGao Awaiting requested review from MaryGao MaryGao will be requested when the pull request is marked ready for review MaryGao is a code owner

@JialinHuang803 JialinHuang803 Awaiting requested review from JialinHuang803 JialinHuang803 will be requested when the pull request is marked ready for review JialinHuang803 is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@maorleger