feat(mutator-framework): add multi-subgraph support and fix TypeScript 6 compatibility

[qiaozha]

Summary

Extends ModelPropertyMutation with multi-subgraph support and fixes TypeScript 6 type cast errors that were breaking the monorepo build.

Changes

mutation-engine.ts

• Add new TypeEdgeSpec interface for specifying type edges during ModelProperty mutation. Supports either a typeToFollow (direct mutate) or referenceToFollow (reference-chain resolution via mutateReference()).

model-property.ts

• Add optional typeOverride parameter to mutate() — an escape hatch to redirect the type edge to an explicit type without overriding buildTypeEdges().
• Add buildTypeEdges() override point for multi-subgraph scenarios where a property needs independent type edges per subgraph.
• Make startTypeEdge() non-abstract with a descriptive error message (throw if neither override is provided).
• Fix TypeScript 6 type cast errors by using intermediate unknown casts (as unknown as MutationFor<...>).

mutation-node.ts

• Improve JSDoc for replace() to clarify when to use replace() vs mutate() and prevent misuse.

Usage example

// Override buildTypeEdges() to wire independent type edges per subgraph
class MyPropertyMutation extends ModelPropertyMutation<MyMutations, MyOptions> {
  protected buildTypeEdges(): TypeEdgeSpec[] {
    return [
      { referenceToFollow: this.sourceType, halfEdge: this.subgraphAEdge() },
      { typeToFollow: myExplicitType, halfEdge: this.subgraphBEdge() },
    ];
  }
}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/mutator-framework@10685

commit: 420813c

[github-actions]

All changed packages have been documented.

• ✅ @typespec/mutator-framework

Show changes

@typespec/mutator-framework - feature ✏️

Add multi-subgraph support to ModelPropertyMutation with a new buildTypeEdges() override point, an optional typeOverride parameter on mutate(), and a new TypeEdgeSpec interface. Also fixes TypeScript 6 type cast compatibility.,> ,> ts,> // Override buildTypeEdges() to wire independent type edges per subgraph,> class MyPropertyMutation extends ModelPropertyMutation<...> {,> protected buildTypeEdges(): TypeEdgeSpec[] {,> return [,> { referenceToFollow: this.sourceType, halfEdge: this.subgraphAEdge() },,> { typeToFollow: myExplicitType, halfEdge: this.subgraphBEdge() },,> ];,> },> },>

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[timotheeguerin]

can you show a bit how you plan on using this?

also is the typescript 6 compatibility part relevant to this PR? we are already using typescript 6 is it just the agent fixing build errors from newly added code that trigger this change entry?

[qiaozha]

@timotheeguerin this is to resolve an issue we found on @alternateType decorators with the mutator framework. From my limited understanding, the alternateType decorator replaces the type node itself with a completely different type that must also be traversed and mutated independently, and the current mutation framework doesn't support this. You can refer to this change for more details on how it was used.

Regarding the TypeScript 6 compatibility, it's about we removed the abstract key word of startTypeEdge method and TypeSript 6 would still require every concrete subclass to implement this startTypeEdge if we don't. Which doesn't make sense with this new change as they can just override the new buildTypeEdge method.