@typespec/compiler 1.13.0-dev.0 → 1.13.0-dev.2

package/dist/src/core/checker.js

@@ -11,7 +11,7 @@ import { compilerAssert, createDiagnosticCollector, ignoreDiagnostics, reportDep
 import { validateInheritanceDiscriminatedUnions } from "./helpers/discriminator-utils.js";
 import { getLocationContext } from "./helpers/location-context.js";
 import { explainStringTemplateNotSerializable } from "./helpers/string-template-utils.js";
-import { typeReferenceToString } from "./helpers/syntax-utils.js";
+import { printIdentifier, printMemberExpressionPath, typeReferenceToString, } from "./helpers/syntax-utils.js";
 import { getEntityName, getTypeName } from "./helpers/type-name-utils.js";
 import { marshalTypeForJs, unmarshalJsToValue } from "./js-marshaller.js";
 import { createDiagnostic } from "./messages.js";
@@ -163,6 +163,10 @@ export function createChecker(program, resolver) {
      * Tracking the template parameters used or not.
      */
     const templateParameterUsageMap = new Map();
+    const templateAccessSymbolCache = new Map();
+    const templateAccessCacheKeys = new WeakMap();
+    const symbolCacheIds = new WeakMap();
+    let nextSymbolCacheId = 1;
     const checker = {
         getTypeForNode,
         checkProgram,
@@ -344,7 +348,7 @@ export function createChecker(program, resolver) {
             }));
             return errorType;
         }
-        if (entity.kind === "TemplateParameter") {
+        if (entity.kind === "TemplateParameter" || entity.kind === "TemplateParameterAccess") {
             if (entity.constraint?.valueType) {
                 // means this template constraint will accept values
                 reportCheckerDiagnostic(createDiagnostic({
@@ -380,7 +384,7 @@ export function createChecker(program, resolver) {
         // If a template parameter that can be a value is used where a value is expected,
         // synthesize a template value placeholder even when the template parameter is mapped
         // from an outer template declaration.
-        if (entity.kind === "TemplateParameter" &&
+        if ((entity.kind === "TemplateParameter" || entity.kind === "TemplateParameterAccess") &&
             entity.constraint?.valueType &&
             entity.constraint.type === undefined) {
             // We must also observe that the template parameter is used here.
@@ -706,7 +710,12 @@ export function createChecker(program, resolver) {
         function visit(node) {
             const entity = checkNode(ctx, node);
             let hasError = false;
-            if (entity !== null && "kind" in entity && entity.kind === "TemplateParameter") {
+            if (entity !== null &&
+                "kind" in entity &&
+                (entity.kind === "TemplateParameter" || entity.kind === "TemplateParameterAccess")) {
+                if (entity.kind === "TemplateParameterAccess") {
+                    return entity;
+                }
                 for (let i = index; i < templateParameters.length; i++) {
                     if (entity.node?.symbol === templateParameters[i].symbol) {
                         reportCheckerDiagnostic(createDiagnostic({ code: "invalid-template-default", target: node }));
@@ -1514,7 +1523,7 @@ export function createChecker(program, resolver) {
         const indexers = [];
         const modelOptions = options.filter((entry) => {
             const [optionNode, option] = entry;
-            if (option.kind === "TemplateParameter") {
+            if (option.kind === "TemplateParameter" || option.kind === "TemplateParameterAccess") {
                 return false;
             }
             if (option.kind !== "Model") {
@@ -1726,6 +1735,10 @@ export function createChecker(program, resolver) {
                 const doc = paramDocs.get(name);
                 if (doc) {
                     docFromCommentForSym.set(memberSym, doc);
+                    const declarationSymbol = memberSym.node?.symbol;
+                    if (declarationSymbol && declarationSymbol !== memberSym) {
+                        docFromCommentForSym.set(declarationSymbol, doc);
+                    }
                 }
             }
         }
@@ -1896,15 +1909,24 @@ export function createChecker(program, resolver) {
                 compilerAssert(false, "Unreachable");
         }
         if (sym) {
-            if (sym.symbolSource) {
-                return [sym.symbolSource];
-            }
-            else {
-                return [sym];
+            const relatedSource = getRelatedSymbolSource(sym);
+            if (relatedSource) {
+                return sym.flags & 4194304 /* SymbolFlags.LateBound */ ? [sym, relatedSource] : [relatedSource];
             }
+            return [sym];
         }
         return undefined; //sym?.symbolSource ?? sym;
     }
+    function getRelatedSymbolSource(sym) {
+        if (sym.symbolSource) {
+            return sym.symbolSource;
+        }
+        const type = sym.type;
+        if (type && isType(type)) {
+            return getTemplateAccessSymbolSource(type);
+        }
+        return undefined;
+    }
     function getTemplateDeclarationsForArgument(ctx, node) {
         const ref = node.parent;
         let resolved = resolveTypeReferenceSym(ctx, ref, false);
@@ -2186,32 +2208,43 @@ export function createChecker(program, resolver) {
             }
         }
         else if (identifier.parent && identifier.parent.kind === SyntaxKind.MemberExpression) {
-            let base = resolver.getNodeLinks(identifier.parent.base).resolvedSymbol;
-            if (base) {
-                if (base.flags & 128 /* SymbolFlags.Alias */) {
-                    base = getAliasedSymbol(CheckContext.DEFAULT, base);
+            const memberExpression = identifier.parent;
+            let baseType = getCompletionBaseType(memberExpression.base);
+            let base = resolver.getNodeLinks(memberExpression.base).resolvedSymbol;
+            if (base && base.flags & 128 /* SymbolFlags.Alias */) {
+                base = getAliasedSymbol(CheckContext.DEFAULT, base);
+            }
+            if (!baseType && base) {
+                baseType = getCompletionBaseTypeFromSymbol(base);
+            }
+            if (baseType && (!base || !!(base.flags & 1024 /* SymbolFlags.TemplateParameter */))) {
+                if (memberExpression.selector === "::") {
+                    addMetaCompletionsForType(baseType);
                 }
-                if (base) {
-                    if (identifier.parent.selector === "::") {
-                        if (base?.node === undefined && base?.declarations && base.declarations.length > 0) {
-                            // Process meta properties separately, such as `::parameters`, `::returnType`
-                            const nodeModels = base?.declarations[0];
-                            if (nodeModels.kind === SyntaxKind.OperationStatement) {
-                                const operation = nodeModels;
-                                addCompletion("parameters", operation.symbol);
-                                addCompletion("returnType", operation.symbol);
-                            }
-                        }
-                        else if (base?.node?.kind === SyntaxKind.ModelProperty) {
-                            // Process meta properties separately, such as `::type`
-                            const metaProperty = base.node;
-                            addCompletion("type", metaProperty.symbol);
+                else {
+                    addMemberCompletionsForType(baseType);
+                }
+            }
+            if (base) {
+                if (memberExpression.selector === "::") {
+                    if (base?.node === undefined && base?.declarations && base.declarations.length > 0) {
+                        // Process meta properties separately, such as `::parameters`, `::returnType`
+                        const nodeModels = base?.declarations[0];
+                        if (nodeModels.kind === SyntaxKind.OperationStatement) {
+                            const operation = nodeModels;
+                            addCompletion("parameters", operation.symbol);
+                            addCompletion("returnType", operation.symbol);
                         }
                     }
-                    else {
-                        addCompletions(base.exports ?? base.members);
+                    else if (base?.node?.kind === SyntaxKind.ModelProperty) {
+                        // Process meta properties separately, such as `::type`
+                        const metaProperty = base.node;
+                        addCompletion("type", metaProperty.symbol);
                     }
                 }
+                else {
+                    addCompletions(base.exports ?? base.members);
+                }
             }
         }
         else {
@@ -2252,6 +2285,101 @@ export function createChecker(program, resolver) {
             }
         }
         return completions;
+        /** Resolve a usable base type for member/meta-member completions. */
+        function getCompletionBaseType(base) {
+            const entity = getTypeOrValueForNode(base, CheckContext.DEFAULT);
+            if (!entity || !isType(entity) || isErrorType(entity)) {
+                if (base.kind === SyntaxKind.Identifier) {
+                    const scopedTemplateParameter = getTemplateParameterTypeFromScope(base);
+                    if (scopedTemplateParameter) {
+                        return resolveTemplateConstraintType(scopedTemplateParameter);
+                    }
+                }
+                const templateBase = probeTemplateAccessBaseEntity(base);
+                return templateBase ? resolveTemplateConstraintType(templateBase) : undefined;
+            }
+            if (isTemplateAccessType(entity)) {
+                return resolveTemplateConstraintType(entity);
+            }
+            return entity;
+        }
+        /** Resolve a completion base type from a symbol when node-based typing is unavailable. */
+        function getCompletionBaseTypeFromSymbol(base) {
+            if (base.flags & 4194304 /* SymbolFlags.LateBound */) {
+                const lateBoundType = base.type;
+                return lateBoundType && isType(lateBoundType)
+                    ? resolveCompletionType(lateBoundType)
+                    : undefined;
+            }
+            if (base.flags & 1024 /* SymbolFlags.TemplateParameter */) {
+                const mapped = checkTemplateParameterDeclaration(CheckContext.DEFAULT, getSymNode(base));
+                return isType(mapped) ? resolveCompletionType(mapped) : undefined;
+            }
+            return undefined;
+        }
+        /** Normalize template access types to their effective constraint for completion. */
+        function resolveCompletionType(type) {
+            return isTemplateAccessType(type) ? resolveTemplateConstraintType(type) : type;
+        }
+        /** Add member completions based on the resolved base type kind. */
+        function addMemberCompletionsForType(baseType) {
+            switch (baseType.kind) {
+                case "Model":
+                    for (const property of walkPropertiesInherited(baseType)) {
+                        const ownerSymbol = baseType.node?.symbol;
+                        const propertySymbol = (ownerSymbol ? getMemberSymbol(ownerSymbol, property.name) : undefined) ??
+                            property.node?.symbol;
+                        if (propertySymbol) {
+                            addCompletion(property.name, propertySymbol);
+                        }
+                    }
+                    return;
+                case "Interface":
+                    for (const [name, operation] of baseType.operations) {
+                        const operationSymbol = operation.node?.symbol;
+                        if (operationSymbol) {
+                            addCompletion(name, operationSymbol);
+                        }
+                    }
+                    return;
+                case "Enum":
+                    for (const [name, member] of baseType.members) {
+                        const enumMemberSymbol = member.node?.symbol;
+                        if (enumMemberSymbol) {
+                            addCompletion(name, enumMemberSymbol);
+                        }
+                    }
+                    return;
+                case "Union":
+                    for (const [name, variant] of baseType.variants) {
+                        if (typeof name === "string" && variant.node?.symbol) {
+                            addCompletion(name, variant.node.symbol);
+                        }
+                    }
+                    return;
+                case "Scalar":
+                    for (const [name, constructor] of baseType.constructors) {
+                        const constructorSymbol = constructor.node?.symbol;
+                        if (constructorSymbol) {
+                            addCompletion(name, constructorSymbol);
+                        }
+                    }
+                    return;
+                case "Namespace":
+                    addCompletions(baseType.node?.symbol?.exports);
+                    return;
+            }
+        }
+        /** Add `::` meta-member completions for the resolved base type. */
+        function addMetaCompletionsForType(baseType) {
+            const baseSymbol = getTypeSymbol(baseType);
+            if (!baseSymbol) {
+                return;
+            }
+            for (const metaMemberName of resolver.getMetaMemberNames(baseSymbol)) {
+                addCompletion(metaMemberName, baseSymbol);
+            }
+        }
         function addCompletions(table) {
             if (!table) {
                 return;
@@ -2273,7 +2401,7 @@ export function createChecker(program, resolver) {
             }
         }
         function addCompletion(key, sym, options = {}) {
-            if (sym.symbolSource) {
+            if (sym.symbolSource && !(sym.flags & 4194304 /* SymbolFlags.LateBound */)) {
                 sym = sym.symbolSource;
             }
             if (!shouldAddCompletion(sym)) {
@@ -2330,7 +2458,7 @@ export function createChecker(program, resolver) {
         }
         resolvedOptions.locationContext ??= getLocationContext(program, node);
         const sym = resolveTypeReferenceSymInternal(ctx, node, resolvedOptions);
-        if (!resolvedOptions.resolveDeclarationOfTemplate) {
+        if (ctx.mapper === undefined && !resolvedOptions.resolveDeclarationOfTemplate) {
             referenceSymCache.set(node, sym);
         }
         return sym;
@@ -2373,6 +2501,10 @@ export function createChecker(program, resolver) {
             if (!base) {
                 return undefined;
             }
+            const directTemplateAccessSym = tryResolveTemplateAccessSymbol(ctx, node, base);
+            if (directTemplateAccessSym) {
+                return directTemplateAccessSym;
+            }
             // when resolving a type reference based on an alias, unwrap the alias.
             if (base.flags & 128 /* SymbolFlags.Alias */) {
                 if (!options.resolveDeclarationOfTemplate && isTemplatedNode(getSymNode(base))) {
@@ -2419,12 +2551,498 @@ export function createChecker(program, resolver) {
                 }
                 base = baseSym;
             }
-            const sym = resolveMemberInContainer(base, node, options);
+            const templateAccessSym = tryResolveTemplateAccessSymbol(ctx, node, base);
+            if (templateAccessSym) {
+                return templateAccessSym;
+            }
+            const sym = resolveMemberInContainer(ctx, base, node, options);
             checkSymbolAccess(options.locationContext, node, sym);
             return sym;
         }
         compilerAssert(false, `Unknown type reference kind "${SyntaxKind[node.kind]}"`, node);
     }
+    /**
+     * Resolve member/meta-member access rooted in a template parameter or template access chain.
+     * Falls back to late-bound symbols when the concrete symbol cannot be safely determined.
+     *
+     * @param ctx Check context for mapper and usage observation.
+     * @param node Member expression being resolved.
+     * @param baseSym Resolved symbol for the member expression base.
+     * @returns The resolved symbol for the template access, or `undefined` when not applicable.
+     */
+    function tryResolveTemplateAccessSymbol(ctx, node, baseSym) {
+        const mappedSymbol = tryResolveMappedTemplateAccessSymbol(ctx, node, baseSym);
+        if (mappedSymbol) {
+            return mappedSymbol;
+        }
+        const baseEntity = getTemplateAccessBaseEntity(ctx, node.base, baseSym);
+        if (!baseEntity) {
+            return undefined;
+        }
+        observeTemplateAccessBase(ctx, baseEntity);
+        const accessedType = resolveTemplateAccessType(ctx, node, baseEntity);
+        const useCache = ctx.mapper === undefined;
+        if (isErrorType(accessedType)) {
+            return createTemplateAccessSymbol(baseEntity, node, errorType, useCache);
+        }
+        if (node.selector === "." &&
+            baseEntity.kind === "TemplateParameterAccess" &&
+            baseEntity.node.selector === "::") {
+            return getPreferredTemplateAccessSymbol(node, accessedType);
+        }
+        if (ctx.mapper !== undefined) {
+            return getPreferredTemplateAccessSymbol(node, accessedType);
+        }
+        return createTemplateAccessSymbol(baseEntity, node, accessedType, useCache);
+    }
+    /**
+     * Resolve template access directly from a mapped template argument when available.
+     *
+     * @param ctx Check context containing the active template mapper.
+     * @param node Member expression being resolved.
+     * @param baseSym Base symbol for the access expression.
+     * @returns A concrete or late-bound symbol for the mapped access, or `undefined`.
+     */
+    function tryResolveMappedTemplateAccessSymbol(ctx, node, baseSym) {
+        if (!ctx.mapper || !(baseSym.flags & 1024 /* SymbolFlags.TemplateParameter */)) {
+            return undefined;
+        }
+        const declared = checkTemplateParameterDeclaration(CheckContext.DEFAULT, getSymNode(baseSym));
+        if (!isType(declared) || declared.kind !== "TemplateParameter") {
+            return undefined;
+        }
+        const mapped = ctx.mapper.getMappedType(declared);
+        if (!isType(mapped) || isTemplateAccessType(mapped)) {
+            return undefined;
+        }
+        if (isUninstantiatedTemplateType(mapped)) {
+            return undefined;
+        }
+        const resolvedType = node.selector === "."
+            ? resolveMemberTypeFromConstraint(mapped, node.id.sv)
+            : resolveMetaTypeFromConstraint(ctx, mapped, node);
+        if (!resolvedType) {
+            return undefined;
+        }
+        return getPreferredTemplateAccessSymbol(node, resolvedType);
+    }
+    /** Return true when a type declaration is templated but has not been instantiated. */
+    function isUninstantiatedTemplateType(type) {
+        if ("templateMapper" in type && type.templateMapper !== undefined) {
+            return false;
+        }
+        const node = type.node;
+        return Boolean(node && "templateParameters" in node && node.templateParameters.length > 0);
+    }
+    /** Return true when the resolved type should remain late-bound due to templating. */
+    function shouldUseLateBoundTemplateAccessType(type) {
+        return "templateMapper" in type && type.templateMapper !== undefined;
+    }
+    /**
+     * Prefer canonical member symbols for resolved template access results when they already exist.
+     * This preserves symbol identity for downstream cloning and doc lookups in instantiated flows.
+     */
+    function getPreferredTemplateAccessSymbol(node, type) {
+        const canonicalMemberSymbol = getCanonicalTemplateAccessMemberSymbol(type);
+        if (canonicalMemberSymbol) {
+            return canonicalMemberSymbol;
+        }
+        if (!shouldUseLateBoundTemplateAccessType(type)) {
+            return getTypeSymbol(type) ?? createLateBoundTypeSymbol(node, type);
+        }
+        return createLateBoundTypeSymbol(node, type);
+    }
+    /** Return the exact instantiated member symbol for a resolved type when one exists. */
+    function getCanonicalTemplateAccessMemberSymbol(type) {
+        switch (type.kind) {
+            case "ModelProperty":
+                return getExactInstantiatedMemberSymbol(type.model?.symbol, type.name, type);
+            case "Operation":
+                return getExactInstantiatedMemberSymbol(type.interface?.symbol, type.name, type);
+            case "EnumMember":
+                return getExactInstantiatedMemberSymbol(type.enum?.symbol, type.name, type);
+            case "UnionVariant":
+                return getExactInstantiatedMemberSymbol(type.union?.symbol, type.name, type);
+            case "ScalarConstructor":
+                return getExactInstantiatedMemberSymbol(type.scalar?.symbol, type.name, type);
+            default:
+                return undefined;
+        }
+    }
+    function getExactInstantiatedMemberSymbol(containerSymbol, memberName, type) {
+        if (!containerSymbol || typeof memberName !== "string") {
+            return undefined;
+        }
+        const memberSymbol = getMemberSymbol(containerSymbol, memberName);
+        return memberSymbol?.type === type ? memberSymbol : undefined;
+    }
+    /**
+     * Resolve the template entity (parameter or access) that acts as the base for a member expression.
+     */
+    function getTemplateAccessBaseEntity(_ctx, baseNode, baseSym) {
+        if (baseSym.flags & 4194304 /* SymbolFlags.LateBound */) {
+            const lateBoundType = baseSym.type;
+            if (lateBoundType && lateBoundType.kind === "TemplateParameterAccess") {
+                return lateBoundType;
+            }
+            return undefined;
+        }
+        if (baseSym.flags & 1024 /* SymbolFlags.TemplateParameter */) {
+            const baseSymbolNode = getSymNode(baseSym);
+            const mapped = checkTemplateParameterDeclaration(CheckContext.DEFAULT, baseSymbolNode);
+            return isType(mapped) && isTemplateAccessType(mapped) ? mapped : undefined;
+        }
+        if (baseNode.kind === SyntaxKind.Identifier) {
+            const templateParameterType = getTemplateParameterTypeFromScope(baseNode);
+            if (templateParameterType) {
+                return templateParameterType;
+            }
+            return undefined;
+        }
+        return undefined;
+    }
+    /** Probe a node for a template access base without surfacing diagnostics. */
+    function probeTemplateAccessBaseEntity(node) {
+        const oldDiagnosticHook = onCheckerDiagnostic;
+        onCheckerDiagnostic = () => { };
+        const entity = checkTypeOrValueReference(CheckContext.DEFAULT, node, false);
+        onCheckerDiagnostic = oldDiagnosticHook;
+        return isType(entity) && isTemplateAccessType(entity) ? entity : undefined;
+    }
+    /** Resolve a template parameter type from lexical scope by identifier name. */
+    function getTemplateParameterTypeFromScope(identifier) {
+        const declaration = findTemplateParameterDeclarationInScope(identifier, identifier.sv);
+        if (!declaration) {
+            return undefined;
+        }
+        const mapped = checkTemplateParameterDeclaration(CheckContext.DEFAULT, declaration);
+        return isType(mapped) && isTemplateAccessType(mapped) ? mapped : undefined;
+    }
+    /** Find the closest template parameter declaration matching the given name. */
+    function findTemplateParameterDeclarationInScope(node, name) {
+        let current = node.parent;
+        while (current) {
+            if ("templateParameters" in current && current.templateParameters) {
+                const declaration = current.templateParameters.find((x) => x.id.sv === name);
+                if (declaration) {
+                    return declaration;
+                }
+            }
+            current = current.parent;
+        }
+        return undefined;
+    }
+    /**
+     * Resolve the resulting type for a template parameter access expression.
+     *
+     * @param ctx Check context for mapper-aware resolution.
+     * @param node Access expression (`.` or `::`) being resolved.
+     * @param baseEntity Template parameter or prior template access chain.
+     * @returns The resolved member/meta-member type, or `errorType` when not guaranteed.
+     */
+    function resolveTemplateAccessType(ctx, node, baseEntity) {
+        const baseType = resolveTemplateAccessBaseType(ctx, baseEntity);
+        if (!baseType) {
+            if (hasErrorTemplateConstraint(baseEntity)) {
+                return errorType;
+            }
+            reportTemplateAccessNotGuaranteed(node, baseEntity);
+            return errorType;
+        }
+        const resolvedType = node.selector === "."
+            ? resolveMemberTypeFromConstraint(baseType, node.id.sv)
+            : resolveMetaTypeFromConstraint(ctx, baseType, node);
+        if (!resolvedType) {
+            reportTemplateAccessNotGuaranteed(node, baseType);
+            return errorType;
+        }
+        return resolvedType;
+    }
+    /**
+     * Resolve the concrete base type that a template access should evaluate against.
+     *
+     * @param ctx Check context containing optional template mapper.
+     * @param baseEntity Template parameter/access entity.
+     * @returns The mapped or constrained base type, if determinable.
+     */
+    function resolveTemplateAccessBaseType(ctx, baseEntity) {
+        if (ctx.mapper && baseEntity.kind === "TemplateParameterAccess") {
+            const mappedBaseType = resolveTemplateAccessBaseType(ctx, baseEntity.base);
+            if (!mappedBaseType) {
+                return undefined;
+            }
+            return baseEntity.node.selector === "."
+                ? resolveMemberTypeFromConstraint(mappedBaseType, baseEntity.node.id.sv)
+                : resolveMetaTypeFromConstraint(ctx, mappedBaseType, baseEntity.node);
+        }
+        if (ctx.mapper && baseEntity.kind === "TemplateParameter") {
+            const mapped = ctx.mapper.getMappedType(baseEntity);
+            if (isType(mapped)) {
+                if (isTemplateAccessType(mapped)) {
+                    return resolveTemplateConstraintType(mapped);
+                }
+                if (isUninstantiatedTemplateType(mapped)) {
+                    return resolveTemplateConstraintType(baseEntity);
+                }
+                return mapped;
+            }
+        }
+        return resolveTemplateConstraintType(baseEntity);
+    }
+    /**
+     * Resolve the terminal non-template constraint type for a template access chain.
+     *
+     * @param templateType Template parameter or access node.
+     * @returns The terminal constrained type, or `undefined` when missing/invalid/cyclic.
+     */
+    function resolveTemplateConstraintType(templateType) {
+        const visited = new Set();
+        let current = templateType;
+        while (true) {
+            if (visited.has(current)) {
+                return undefined;
+            }
+            visited.add(current);
+            const constraintType = current.constraint?.type;
+            if (!constraintType || isErrorType(constraintType)) {
+                return undefined;
+            }
+            if (!isTemplateAccessType(constraintType)) {
+                return constraintType;
+            }
+            current = constraintType;
+        }
+    }
+    /** Return true when a template access chain includes an error constraint. */
+    function hasErrorTemplateConstraint(templateType) {
+        let current = templateType;
+        while (true) {
+            const constraintType = current.constraint?.type;
+            if (constraintType && isErrorType(constraintType)) {
+                return true;
+            }
+            if (current.kind !== "TemplateParameterAccess") {
+                return false;
+            }
+            current = current.base;
+        }
+    }
+    /** Track template parameter usage for a template access base chain. */
+    function observeTemplateAccessBase(ctx, base) {
+        const root = getTemplateAccessRoot(base);
+        ctx.observeTemplateParameter(root);
+        templateParameterUsageMap.set(root.node, true);
+    }
+    /** Return the root template parameter for a template access chain. */
+    function getTemplateAccessRoot(base) {
+        let current = base;
+        while (current.kind === "TemplateParameterAccess") {
+            current = current.base;
+        }
+        return current;
+    }
+    /** Resolve `.` access from a constrained type by kind-specific member lookup. */
+    function resolveMemberTypeFromConstraint(constraintType, memberName) {
+        const canonicalMemberType = getCanonicalResolvedMemberType(constraintType, memberName);
+        if (canonicalMemberType) {
+            return canonicalMemberType;
+        }
+        switch (constraintType.kind) {
+            case "Model":
+                for (const property of walkPropertiesInherited(constraintType)) {
+                    if (property.name === memberName) {
+                        return property;
+                    }
+                }
+                return undefined;
+            case "Interface":
+                return constraintType.operations.get(memberName);
+            case "Enum":
+                return constraintType.members.get(memberName);
+            case "Union":
+                return constraintType.variants.get(memberName);
+            case "Scalar":
+                return constraintType.constructors.get(memberName);
+            default:
+                return undefined;
+        }
+    }
+    function getCanonicalResolvedMemberSymbol(containerType, memberName) {
+        switch (containerType.kind) {
+            case "Model":
+            case "Interface":
+            case "Enum":
+            case "Union":
+            case "Scalar":
+                break;
+            default:
+                return undefined;
+        }
+        const containerSymbol = containerType.symbol;
+        if (containerSymbol === undefined || !containerSymbol.members) {
+            return undefined;
+        }
+        let memberSymbol = getMemberSymbol(containerSymbol, memberName);
+        if (!memberSymbol?.type && containerSymbol.flags & 4194304 /* SymbolFlags.LateBound */) {
+            lateBindMembers(containerType);
+            memberSymbol = getMemberSymbol(containerSymbol, memberName);
+        }
+        return memberSymbol;
+    }
+    function getCanonicalResolvedMemberType(containerType, memberName) {
+        const memberType = getCanonicalResolvedMemberSymbol(containerType, memberName)?.type;
+        return memberType && isType(memberType) ? memberType : undefined;
+    }
+    /**
+     * Resolve `::` meta-member access from a constrained type.
+     *
+     * @param ctx Check context used for symbol-to-entity evaluation.
+     * @param constraintType Base constrained type.
+     * @param node Meta-member expression node.
+     * @returns The resolved meta-member type, `unknownType` for projection-only cases, or `undefined`.
+     */
+    function resolveMetaTypeFromConstraint(ctx, constraintType, node) {
+        if (constraintType.kind === "ModelProperty" && node.id.sv === "type") {
+            return constraintType.type;
+        }
+        if (constraintType.kind === "Operation") {
+            switch (node.id.sv) {
+                case "parameters":
+                    return constraintType.parameters;
+                case "returnType":
+                    return constraintType.returnType;
+            }
+        }
+        const constraintSymbol = getTypeSymbol(constraintType);
+        if (!constraintSymbol) {
+            return undefined;
+        }
+        const metaMemberNames = resolver.getMetaMemberNames(constraintSymbol);
+        if (!metaMemberNames.includes(node.id.sv)) {
+            return undefined;
+        }
+        if (isReflectionMetaProjectionSymbol(constraintSymbol)) {
+            // Reflection model symbols expose meta-member names by projection, but their
+            // underlying nodes are not concrete ModelProperty/Operation nodes.
+            return unknownType;
+        }
+        const resolved = resolver.resolveMetaMemberByName(constraintSymbol, node.id.sv);
+        if (resolved.resolutionResult & ResolutionResultFlags.Resolved && resolved.resolvedSymbol) {
+            const entity = checkTypeOrValueReferenceSymbol(ctx, resolved.resolvedSymbol, node, false);
+            if (entity === null) {
+                return undefined;
+            }
+            if (entity.entityKind === "Indeterminate") {
+                return entity.type;
+            }
+            return isType(entity) ? entity : undefined;
+        }
+        return unknownType;
+    }
+    /** Return true for TypeSpec.Reflection model symbols backed by projection metadata. */
+    function isReflectionMetaProjectionSymbol(sym) {
+        return (sym.node?.kind === SyntaxKind.ModelStatement &&
+            sym.parent?.name === "Reflection" &&
+            sym.parent?.parent?.name === "TypeSpec");
+    }
+    /** Report an invalid-ref diagnostic for unsupported template member/meta-member access. */
+    function reportTemplateAccessNotGuaranteed(node, baseType) {
+        reportCheckerDiagnostic(createDiagnostic({
+            code: "invalid-ref",
+            messageId: node.selector === "." ? "member" : "metaProperty",
+            format: { kind: getTemplateAccessKindName(baseType), id: node.id.sv },
+            target: node,
+        }));
+    }
+    /** Get the diagnostic kind label used when template access resolution fails. */
+    function getTemplateAccessKindName(type) {
+        switch (type.kind) {
+            case "Model":
+            case "ModelProperty":
+            case "Enum":
+            case "Interface":
+            case "Union":
+            case "Operation":
+            case "Scalar":
+            case "TemplateParameter":
+            case "TemplateParameterAccess":
+                return type.kind;
+            default:
+                return "Type";
+        }
+    }
+    /** Type guard for template parameters and template parameter access types. */
+    function isTemplateAccessType(type) {
+        return type.kind === "TemplateParameter" || type.kind === "TemplateParameterAccess";
+    }
+    /**
+     * Create (or retrieve from cache) a late-bound symbol representing template access.
+     *
+     * @param base Template parameter/access base.
+     * @param node Member expression node.
+     * @param constraintType Resolved constraint for the access result.
+     * @param useCache Whether to reuse/access symbol cache.
+     * @returns A symbol whose type is `TemplateParameterAccess`.
+     */
+    function createTemplateAccessSymbol(base, node, constraintType, useCache = true) {
+        const cacheKey = getTemplateAccessCacheKey(base, node);
+        if (useCache) {
+            const existing = templateAccessSymbolCache.get(cacheKey);
+            if (existing) {
+                return existing;
+            }
+        }
+        const constraint = {
+            entityKind: "MixedParameterConstraint",
+            node,
+            type: constraintType,
+        };
+        const type = createAndFinishType({
+            kind: "TemplateParameterAccess",
+            node,
+            base,
+            path: printMemberExpressionPath(getTemplateAccessPath(base), node.selector, node.id.sv),
+            constraint,
+        });
+        templateAccessCacheKeys.set(type, cacheKey);
+        const symbol = createSymbol(node, node.id.sv, 4194304 /* SymbolFlags.LateBound */);
+        mutate(symbol).type = type;
+        if (useCache) {
+            templateAccessSymbolCache.set(cacheKey, symbol);
+        }
+        return symbol;
+    }
+    /** Compute the user-facing access path for a template access chain. */
+    function getTemplateAccessPath(base) {
+        return base.kind === "TemplateParameterAccess" ? base.path : printIdentifier(base.node.id.sv);
+    }
+    /** Build a stable cache key for a template access symbol/type chain. */
+    function getTemplateAccessCacheKey(base, node) {
+        let baseKey;
+        if (base.kind === "TemplateParameterAccess") {
+            const cacheKey = templateAccessCacheKeys.get(base);
+            compilerAssert(cacheKey, "Expected template access cache key");
+            baseKey = cacheKey;
+        }
+        else {
+            baseKey = `tp:${getSymbolCacheId(base.node.symbol)}`;
+        }
+        return `${baseKey}${node.selector}${node.id.sv}`;
+    }
+    /** Resolve the merged symbol associated with a type, when one exists. */
+    function getTypeSymbol(type) {
+        return type.node?.symbol ? getMergedSymbol(type.node.symbol) : undefined;
+    }
+    /** Get a stable numeric id for a symbol used in template access cache keys. */
+    function getSymbolCacheId(sym) {
+        const existing = symbolCacheIds.get(sym);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const id = nextSymbolCacheId++;
+        symbolCacheIds.set(sym, id);
+        return id;
+    }
     function checkSymbolAccess(sourceLocation, node, symbol) {
         if (!symbol)
             return;
@@ -2468,7 +3086,11 @@ export function createChecker(program, resolver) {
             target: node,
         }));
     }
-    function resolveMemberInContainer(base, node, options) {
+    function resolveMemberInContainer(ctx, base, node, options) {
+        const symbolFromType = resolveMemberOnSymbolType(ctx, base, node);
+        if (symbolFromType) {
+            return symbolFromType;
+        }
         const { finalSymbol: sym, resolvedSymbol: nextSym } = resolver.resolveMemberExpressionForSym(base, node, options);
         const symbol = nextSym ?? sym;
         if (symbol) {
@@ -2540,6 +3162,100 @@ export function createChecker(program, resolver) {
                 return "Type";
         }
     }
+    /**
+     * Resolve a member/meta-member access from the base symbol's resolved type.
+     *
+     * @param ctx Check context.
+     * @param base Base symbol.
+     * @param node Member expression to resolve.
+     * @returns Concrete symbol, late-bound symbol, or `undefined` when unresolved.
+     */
+    function resolveMemberOnSymbolType(ctx, base, node) {
+        const baseType = getMemberResolutionType(ctx, base);
+        if (!baseType) {
+            return undefined;
+        }
+        const resolvedBaseType = isTemplateAccessType(baseType)
+            ? resolveTemplateAccessBaseType(ctx, baseType)
+            : baseType;
+        if (!resolvedBaseType) {
+            return undefined;
+        }
+        if (node.selector === ".") {
+            const table = base.exports ?? base.members;
+            if (table) {
+                const directMember = resolver.getAugmentedSymbolTable(table).get(node.id.sv);
+                if (directMember) {
+                    return directMember;
+                }
+            }
+            const canonicalMember = getCanonicalResolvedMemberSymbol(resolvedBaseType, node.id.sv);
+            if (canonicalMember) {
+                return canonicalMember;
+            }
+        }
+        const resolvedType = node.selector === "."
+            ? resolveMemberTypeFromConstraint(resolvedBaseType, node.id.sv)
+            : resolveMetaTypeFromConstraint(ctx, resolvedBaseType, node);
+        if (!resolvedType) {
+            return undefined;
+        }
+        if (node.selector === "::" &&
+            node.id.sv === "type" &&
+            resolvedType.kind === "TemplateParameterAccess" &&
+            resolvedType.base.kind === "TemplateParameterAccess" &&
+            resolvedType.base.node.selector === ".") {
+            const sourceProperty = resolveTemplateConstraintType(resolvedType.base);
+            if (sourceProperty) {
+                return getTypeSymbol(sourceProperty) ?? createLateBoundTypeSymbol(node, sourceProperty);
+            }
+        }
+        return getPreferredTemplateAccessSymbol(node, resolvedType);
+    }
+    /** Resolve the effective type used for member lookup on a base symbol. */
+    function getMemberResolutionType(_ctx, base) {
+        if (base.flags & 4194304 /* SymbolFlags.LateBound */) {
+            return base.type && isType(base.type) ? base.type : undefined;
+        }
+        if (base.flags & 65536 /* SymbolFlags.Member */) {
+            return base.type && isType(base.type) ? base.type : undefined;
+        }
+        return undefined;
+    }
+    /** Create a late-bound symbol carrying a precomputed type for member resolution. */
+    function createLateBoundTypeSymbol(node, type) {
+        const symbol = createSymbol(node, node.id.sv, 4194304 /* SymbolFlags.LateBound */);
+        mutate(symbol).type = type;
+        const symbolSource = getTemplateAccessSymbolSource(type);
+        if (symbolSource) {
+            mutate(symbol).symbolSource = symbolSource;
+        }
+        return symbol;
+    }
+    /** Get the best source symbol to associate with a template-access-derived symbol. */
+    function getTemplateAccessSymbolSource(type) {
+        const symbolSource = type.kind === "ModelProperty"
+            ? getModelPropertySymbolSource(type)
+            : (getCanonicalTemplateAccessMemberSymbol(type) ?? getTypeSymbol(type));
+        return symbolSource?.symbolSource ?? symbolSource;
+    }
+    function getModelPropertySymbolSource(type) {
+        let fallback;
+        for (let property = type; property; property = property.sourceProperty) {
+            const symbolSource = getCanonicalTemplateAccessMemberSymbol(property) ??
+                (property.model?.symbol && typeof property.name === "string"
+                    ? getMemberSymbol(property.model.symbol, property.name)
+                    : undefined) ??
+                getTypeSymbol(property);
+            if (symbolSource) {
+                fallback ??= symbolSource;
+                if (!property.sourceProperty) {
+                    return symbolSource;
+                }
+            }
+        }
+        return fallback;
+    }
     /**
      * Return the symbol that is aliased by this alias declaration. If no such symbol is aliased,
      * return the symbol for the alias instead. For member containers which need to be late bound
@@ -2550,7 +3266,12 @@ export function createChecker(program, resolver) {
         const node = getSymNode(aliasSymbol);
         const links = resolver.getSymbolLinks(aliasSymbol);
         if (!links.aliasResolutionIsTemplate) {
-            return links.aliasedSymbol ?? resolver.getNodeLinks(node).resolvedSymbol;
+            const aliased = links.aliasedSymbol ?? resolver.getNodeLinks(node).resolvedSymbol;
+            if (aliased && isTemplatedNode(getSymNode(aliased))) {
+                const aliasType = getTypeForNode(node, ctx);
+                return lateBindContainer(aliasType, aliasSymbol);
+            }
+            return aliased;
         }
         // Otherwise for templates we need to get the type and retrieve the late bound symbol.
         const aliasType = getTypeForNode(node, ctx);
@@ -2607,7 +3328,9 @@ export function createChecker(program, resolver) {
                 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;
@@ -2636,7 +3359,9 @@ export function createChecker(program, resolver) {
             let str = node.head.value;
             for (const [span, typeOrValue] of spanTypeOrValues) {
                 if (typeOrValue !== null &&
-                    (!("kind" in typeOrValue) || typeOrValue.kind !== "TemplateParameter")) {
+                    (!("kind" in typeOrValue) ||
+                        (typeOrValue.kind !== "TemplateParameter" &&
+                            typeOrValue.kind !== "TemplateParameterAccess"))) {
                     compilerAssert(typeOrValue !== null && isValue(typeOrValue), "Expected value.");
                     str += stringifyValueForTemplate(typeOrValue);
                 }
@@ -3265,7 +3990,7 @@ export function createChecker(program, resolver) {
             if (target.kind === "Scalar" || target.kind === "ScalarConstructor") {
                 return target;
             }
-            else if (target.kind === "TemplateParameter") {
+            else if (target.kind === "TemplateParameter" || target.kind === "TemplateParameterAccess") {
                 const callable = target.constraint && constraintIsCallable(target.constraint);
                 if (!callable) {
                     reportCheckerDiagnostic(createDiagnostic({
@@ -3751,7 +4476,7 @@ export function createChecker(program, resolver) {
             return entity.type;
         }
         if (isType(entity)) {
-            if (entity.kind === "TemplateParameter") {
+            if (entity.kind === "TemplateParameter" || entity.kind === "TemplateParameterAccess") {
                 if (entity.constraint === undefined || entity.constraint.type !== undefined) {
                     // means this template constraint will accept values
                     reportCheckerDiagnostic(createDiagnostic({
@@ -3848,8 +4573,11 @@ export function createChecker(program, resolver) {
      * access a symbol for a type that is created during the check phase.
      */
     function lateBindMemberContainer(type) {
-        if (type.symbol)
+        const existingSymbol = type.symbol;
+        if (existingSymbol &&
+            !(isTemplateInstance(type) && !(existingSymbol.flags & 4194304 /* SymbolFlags.LateBound */))) {
             return;
+        }
         switch (type.kind) {
             case "Model":
                 type.symbol = createSymbol(type.node, type.name, 2 /* SymbolFlags.Model */ | 4194304 /* SymbolFlags.LateBound */);
@@ -3906,6 +4634,10 @@ export function createChecker(program, resolver) {
             }
             const sym = createSymbol(member.node, member.name, kind | 4194304 /* SymbolFlags.LateBound */, containerSym);
             mutate(sym).type = member;
+            const symbolSource = getTypeSymbol(member);
+            if (symbolSource) {
+                mutate(sym).symbolSource = symbolSource.symbolSource ?? symbolSource;
+            }
             compilerAssert(containerSym.members, "containerSym.members is undefined");
             containerMembers.set(member.name, sym);
         }
@@ -4024,7 +4756,9 @@ export function createChecker(program, resolver) {
     }
     function checkSpreadProperty(ctx, parentModelSym, targetNode, parentModel) {
         const targetType = getTypeForNode(targetNode, ctx);
-        if (targetType.kind === "TemplateParameter" || isErrorType(targetType)) {
+        if (targetType.kind === "TemplateParameter" ||
+            targetType.kind === "TemplateParameterAccess" ||
+            isErrorType(targetType)) {
             return [[], undefined];
         }
         if (targetType.kind !== "Model") {
@@ -4108,7 +4842,7 @@ export function createChecker(program, resolver) {
         linkMapper(type, ctx.mapper);
         const shouldRunDecorators = !ctx.hasFlags(CheckFlags.InTemplateDeclaration);
         if (!parentTemplate || shouldRunDecorators) {
-            const docComment = docFromCommentForSym.get(sym);
+            const docComment = getDocCommentForSymbol(sym) ?? getOperationParameterDocComment(prop);
             if (docComment) {
                 type.decorators.unshift(createDocFromCommentDecorator("self", docComment));
             }
@@ -4116,6 +4850,20 @@ export function createChecker(program, resolver) {
         pendingResolutions.finish(sym, ResolutionKind.Type);
         return finishType(type, { skipDecorators: !shouldRunDecorators });
     }
+    function getOperationParameterDocComment(prop) {
+        if (prop.parent?.kind !== SyntaxKind.ModelExpression) {
+            return undefined;
+        }
+        const signature = prop.parent.parent;
+        if (signature?.kind !== SyntaxKind.OperationSignatureDeclaration) {
+            return undefined;
+        }
+        const operation = signature.parent;
+        if (operation?.kind !== SyntaxKind.OperationStatement) {
+            return undefined;
+        }
+        return extractParamDocs(operation).get(prop.id.sv);
+    }
     function createDocFromCommentDecorator(key, doc) {
         return {
             decorator: docFromCommentDecorator,
@@ -4125,6 +4873,32 @@ export function createChecker(program, resolver) {
             ],
         };
     }
+    function getDocCommentForSymbol(sym) {
+        if (!sym) {
+            return undefined;
+        }
+        const relatedSource = getRelatedSymbolSource(sym);
+        return (docFromCommentForSym.get(sym) ??
+            (relatedSource && docFromCommentForSym.get(relatedSource)) ??
+            (sym.flags & 4194304 /* SymbolFlags.LateBound */ && sym.type && isType(sym.type)
+                ? getDocCommentForType(sym.type)
+                : undefined));
+    }
+    function getDocCommentForType(type) {
+        if (!type) {
+            return undefined;
+        }
+        if (type.kind === "ModelProperty") {
+            for (let property = type; property; property = property.sourceProperty) {
+                const docComment = getDocCommentForSymbol(getTemplateAccessSymbolSource(property));
+                if (docComment) {
+                    return docComment;
+                }
+            }
+            return undefined;
+        }
+        return getDocCommentForSymbol(getTemplateAccessSymbolSource(type));
+    }
     function checkDefaultValue(ctx, defaultNode, type) {
         if (isErrorType(type)) {
             // if the prop type is an error we don't need to validate again.
@@ -5196,7 +5970,7 @@ export function createChecker(program, resolver) {
     function cloneTypeForSymbol(sym, type, additionalProps = {}) {
         let clone = initializeClone(type, additionalProps);
         if ("decorators" in clone) {
-            const docComment = docFromCommentForSym.get(sym);
+            const docComment = getDocCommentForSymbol(sym) ?? getDocCommentForType(type);
             if (docComment) {
                 clone.decorators.push(createDocFromCommentDecorator("self", docComment));
             }