[compiler] Resolve members through template parameters. by witemple-msft · Pull Request #9868 · microsoft/typespec

witemple-msft · 2026-03-02T18:33:44Z

This PR enables resolving member symbols (properties, metaproperties) through template parameters based on constraints.

It accomplishes this by adding a new Type node, TemplateParameterAccess, which is a semantic equivalent of a member expression where the base of the member access is a template parameter or another template parameter access expression. These are only visible inside the context of template declarations. Otherwise, like template parameters, they become "resolved" to concrete types when the template is instantiated.

This allows you to invoke metaproperties such as ::returnType when a template item is constrained to an Operation. This is recursive, so I.o::returnType is allowed if I is an interface that is proven to have an operation named o. proven is the keyword. Members only resolve if the constraint guarantees their presence.

This feature enables much more powerful templates. For example:

model Resource {
  @visibility(Lifecycle.Read)
  id: string;
}

@format("uuid")
scalar uuid extends string;

model MyResource extends Resource {
  @visibility(Lifecycle.Read)
  id: uuid;

  myProp: string;
}

@error
model Error {
  @minValue(400)
  @maxValue(599)
  @statusCode code: int32;
  message: string;
}

interface Ops<R extends Resource> {
  // Notice, we can actually use the type of the specific `id` property of this resource, enriched with all of its metadata,
  // because the constraint `Resource` guarantees it is present.
  get(@path id: R.id): Read<R> | Error;
  @post
  create(@bodyRoot resource: Create<R>): Read<R> | Error;
  // ...
}

interface MyOps extends Ops<MyResource> {}

⚠️ This PR was almost entirely generated by GitHub Copilot CLI.

…ateparameter-metaproperties

pkg-pr-new · 2026-03-02T20:17:49Z

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@9868

npm i https://pkg.pr.new/@typespec/html-program-viewer@9868

npm i https://pkg.pr.new/@typespec/http-server-csharp@9868

npm i https://pkg.pr.new/@typespec/tspd@9868

commit: e582f35

github-actions · 2026-03-02T20:18:47Z

All changed packages have been documented.

✅ @typespec/compiler
✅ @typespec/html-program-viewer
✅ @typespec/http-server-csharp
✅ @typespec/tspd

Show changes

`@typespec/compiler` - feature ✏️

Enabled resolution of member properties and metaproperties through template parameters based on constraints.

`@typespec/html-program-viewer` - internal ✏️

Updated some packages to account for introduction of new TemplateParameterAccess virtual type.

`@typespec/http-server-csharp` - internal ✏️

Updated some packages to account for introduction of new TemplateParameterAccess virtual type.

`@typespec/tspd` - internal ✏️

Updated some packages to account for introduction of new TemplateParameterAccess virtual type.

azure-sdk · 2026-03-02T20:42:53Z

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

witemple-msft · 2026-03-02T22:42:19Z

Solid illustration of functionality here (see ResourceOperations): Playground

…ateparameter-metaproperties

Copilot

Pull request overview

This PR introduces a new TemplateParameterAccess type to the TypeSpec compiler, enabling member access (.) and meta-member access (::) through template parameters based on their constraints. For instance, if R extends Resource and Resource guarantees a property id, then R.id can be used as a type in template declarations.

Changes:

Adds a new TemplateParameterAccess internal type and comprehensive resolution logic in checker.ts and name-resolver.ts for resolving member/meta-member access through template parameter constraints
Updates all subsystems that handle the Type union (semantic walker, type relation checker, string template utils, type name utils, completions, hover, document highlight) to recognize the new type
Updates dependent packages (html-program-viewer, http-server-csharp, tspd) and adds tests for completions, hover, document highlighting, and reference resolution

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`packages/compiler/src/core/types.ts`	Adds `TemplateParameterAccess` interface and includes it in the `Type` union
`packages/compiler/src/core/checker.ts`	Core logic for resolving template parameter access (member & meta-member), caching, and completions
`packages/compiler/src/core/name-resolver.ts`	Adds `getMetaMemberNames` API to expose available meta-member names for completion and validation
`packages/compiler/src/core/semantic-walker.ts`	Adds navigation support for `TemplateParameterAccess` in the semantic walker
`packages/compiler/src/core/type-relation-checker.ts`	Treats `TemplateParameterAccess` like `TemplateParameter` (uses constraint for assignability)
`packages/compiler/src/core/helpers/type-name-utils.ts`	Returns `path` as the type name for `TemplateParameterAccess`
`packages/compiler/src/core/helpers/string-template-utils.ts`	Handles `TemplateParameterAccess` in string template serialization check
`packages/compiler/src/server/type-signature.ts`	Renders hover signature for `TemplateParameterAccess` as `(template access)`
`packages/compiler/test/checker/references.test.ts`	Tests for resolving references through template parameter constraints
`packages/compiler/test/checker/operations.test.ts`	Tests that operation parameters resolve correctly with template member types
`packages/compiler/test/server/completion.test.ts`	Tests for IDE completions through constrained template parameters
`packages/compiler/test/server/get-hover.test.ts`	Tests for hover information on template parameter access expressions
`packages/compiler/test/server/document-highlight.test.ts`	Tests for document highlighting of template access references
`packages/html-program-viewer/src/react/type-config.ts`	Registers `TemplateParameterAccess` in the program viewer UI
`packages/http-server-csharp/src/lib/service.ts`	Handles `TemplateParameterAccess` as an unsupported type (returns undefined)
`packages/tspd/src/ref-doc/utils/type-signature.ts`	Renders `TemplateParameterAccess` signature in documentation generation
`.chronus/changes/*.md`	Two changeset entries for the compiler (feature) and dependent packages (internal)

Copilot · 2026-03-03T17:12:36Z

packages/compiler/src/core/types.ts

+export interface TemplateParameterAccess extends BaseType {
+  kind: "TemplateParameterAccess";
+  /** @internal */
+  node: MemberExpressionNode;
+  /** @internal */
+  base: TemplateParameter | TemplateParameterAccess;
+  /** @internal */
+  path: string;
+  /** @internal */
+  cacheKey: string;
+  /** @internal */
+  constraint?: MixedParameterConstraint;
+}


The TemplateParameterAccess interface is missing the JSDoc documentation that TemplateParameter has. TemplateParameter is documented with a description of when it can appear, a warning about what you might be missing if you see it, and an @experimental tag. The new TemplateParameterAccess should have analogous documentation explaining that this type represents a member access rooted in a template parameter within template declarations, and should similarly carry an @experimental tag (since it's closely related to the experimental TemplateParameter type).

Copilot · 2026-03-03T17:12:36Z

packages/compiler/src/core/semantic-walker.ts

+/** Emit semantic walker events for template parameter access nodes. */
+function navigateTemplateParameterAccess(
+  type: TemplateParameterAccess,
+  context: NavigationContext,
+) {
+  if (checkVisited(context.visited, type)) {
+    return;
+  }
+  if (context.emit("templateParameterAccess", type) === ListenerFlow.NoRecursion) return;
+}


The navigateTemplateParameterAccess function does not emit the exitTemplateParameterAccess event, even though exitTemplateParameterAccess is included in the eventNames array (line 518). This inconsistency means that any listener registered for exitTemplateParameterAccess will never be called. Note that navigateTemplateParameter has the same issue (it also doesn't emit its exit event), but the new TemplateParameterAccess follows this same pattern, perpetuating a pre-existing inconsistency in the codebase. If this is intentional (because these types don't have children to navigate), the exitTemplateParameterAccess entry in eventNames should be removed to avoid confusing users who register exit listeners.

Copilot · 2026-03-03T17:12:37Z

packages/compiler/src/core/name-resolver.ts

+  /** Get the available meta-member names for a symbol's meta-type prototype. */
+  function getMetaMemberNames(baseSym: Sym): readonly string[] {
+    const baseNode = getSymNode(baseSym);
+    const prototype = getMetaTypePrototypeForSymbol(baseSym, baseNode);
+    return prototype ? [...prototype.keys()] : [];
+  }


In resolveMetaMemberByName (name-resolver.ts line 718), the lookup only uses metaTypePrototypes.get(baseNode.kind) without the Reflection model fallback logic. However, getMetaMemberNames (added in this PR) uses getMetaTypePrototypeForSymbol which includes the Reflection fallback. This creates an inconsistency: getMetaMemberNames can return meta-member names for Reflection.ModelProperty and Reflection.Operation symbols, but resolveMetaMemberByName called with the same symbols would return NotFound. Fortunately, resolveMetaTypeFromConstraint in checker.ts handles this by returning unknownType early for Reflection meta projection symbols (line 4012-4016), so the resolveMetaMemberByName call at line 4018 is never reached for those cases. However, this asymmetry is fragile and could cause bugs if the guard at line 4012 is ever relaxed or if resolveMetaMemberByName is called directly on Reflection symbols from other code paths.

Copilot · 2026-03-03T17:12:37Z

packages/compiler/src/core/checker.ts

      if (typeOrValue !== null) {
        if (isValue(typeOrValue)) {
          hasValue = true;
-        } else if ("kind" in typeOrValue && typeOrValue.kind === "TemplateParameter") {
+        } else if (
+          "kind" in typeOrValue &&
+          (typeOrValue.kind === "TemplateParameter" ||
+            typeOrValue.kind === "TemplateParameterAccess")
+        ) {
          if (typeOrValue.constraint) {
            if (typeOrValue.constraint.valueType) {
              hasValue = true;


In the checkStringTemplateExpresion function (checker.ts), the detection phase at lines 4486-4490 was updated to handle TemplateParameterAccess. However, the value-building loop at line 4522 still only checks typeOrValue.kind !== "TemplateParameter" and does not also exclude "TemplateParameterAccess". This means that if a TemplateParameterAccess with only a valueType constraint (no type constraint) appears as a span in a value-mode string template, the code will incorrectly attempt to treat it as a value (reaching the compilerAssert(isValue(typeOrValue), "Expected value.") at line 4524), causing a runtime crash. The condition on line 4522 should also exclude "TemplateParameterAccess" to be consistent with the detection phase above.

timotheeguerin · 2026-03-04T15:41:03Z

.chronus/changes/witemple-msft-templateparameter-metaproperties-2026-2-2-13-17-55.md

+  - "@typespec/compiler"
+---
+
+Enabled resolution of member properties and metaproperties through template parameters based on constraints.


Could we show some code examples?

timotheeguerin · 2026-03-04T15:42:36Z

packages/compiler/test/checker/references.test.ts

+
+      const diagnostics = await testHost.diagnose("./main.tsp");
+
+      expectDiagnostics(diagnostics, [


nit: don't need the array wrap

timotheeguerin · 2026-03-04T15:43:05Z

packages/compiler/test/checker/operations.test.ts

+    const idParam = myGet.parameters.properties.get("id");
+    ok(idParam);
+    strictEqual(idParam.type.kind, "Scalar");
+    strictEqual((idParam.type as any).name, "uuid");


is the as any necessary after the strictEqual above?

timotheeguerin · 2026-03-04T15:45:06Z

packages/compiler/src/core/types.ts

+  /** @internal */
+  base: TemplateParameter | TemplateParameterAccess;
+  /** @internal */
+  path: string;


what does path corespond to? and cacheKey?

timotheeguerin · 2026-03-04T15:48:26Z

packages/compiler/src/core/checker.ts

+   * @param baseEntity Template parameter or prior template access chain.
+   * @returns The resolved member/meta-member type, or `errorType` when not guaranteed.
+   */
+  function resolveTemplateAccessType(


would that work for values?

witemple-msft added 4 commits March 2, 2026 13:13

First stab

4e79eed

Better hover

4d2f9c5

chronus

86556bb

format

537a6b3

microsoft-github-policy-service bot added compiler:core Issues for @typespec/compiler emitter:openapi3 Issues for @typespec/openapi3 emitter labels Mar 2, 2026

witemple-msft added 3 commits March 2, 2026 14:45

Properly resolve bound template accesses

c8da23b

Updated aux packages

5e695f4

chronus

9e44d82

microsoft-github-policy-service bot added tspd Issues for the tspd tool ui:type-graph-viewer labels Mar 2, 2026

Merge remote-tracking branch 'upstream/main' into witemple-msft/templ…

4fc61fa

…ateparameter-metaproperties

witemple-msft added the int:azure-specs Run integration tests against azure-rest-api-specs label Mar 2, 2026

witemple-msft added 3 commits March 3, 2026 08:59

Merge remote-tracking branch 'upstream/main' into witemple-msft/templ…

d863620

…ateparameter-metaproperties

Some changes from code review

e39b254

Some more docs

6bb36af

witemple-msft marked this pull request as ready for review March 3, 2026 17:02

witemple-msft requested review from AlitzelMendez, RodgeFu, bterlson, chrisradek, markcowl and timotheeguerin as code owners March 3, 2026 17:02

witemple-msft requested a review from Copilot March 3, 2026 17:02

Copilot started reviewing on behalf of witemple-msft March 3, 2026 17:03 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

timotheeguerin reviewed Mar 4, 2026

View reviewed changes


		const diagnostics = await testHost.diagnose("./main.tsp");

		expectDiagnostics(diagnostics, [

Conversation

witemple-msft commented Mar 2, 2026

Uh oh!

pkg-pr-new bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

@typespec/compiler - feature ✏️

@typespec/html-program-viewer - internal ✏️

@typespec/http-server-csharp - internal ✏️

@typespec/tspd - internal ✏️

Uh oh!

azure-sdk commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

witemple-msft commented Mar 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

timotheeguerin Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pkg-pr-new bot commented Mar 2, 2026 •

edited

Loading

github-actions bot commented Mar 2, 2026 •

edited

Loading

`@typespec/compiler` - feature ✏️

`@typespec/html-program-viewer` - internal ✏️

`@typespec/http-server-csharp` - internal ✏️

`@typespec/tspd` - internal ✏️

azure-sdk commented Mar 2, 2026 •

edited

Loading