[TCGC] Warn when @alternateType with external type is applied to model property

[Copilot]

Plan: Check for external type on model property

• Understand the codebase and existing tests
• Add validation in $alternateType decorator to check when external type is used on ModelProperty
• Add diagnostic message for this case
• Add test cases to verify the warning is reported
• Add changelog entry
• Update decorator documentation
• Request code review

Summary

This PR adds a warning when @alternateType decorator with external type information is applied to model properties.

Problem: According to the issue, using @@alternateType(FieldWithExternalType.name, { identity: "crate::models::HandWrittenType" }, "rust") doesn't work and should warn the user.

Solution: Added validation in the $alternateType decorator that:

1. Checks if the source is a ModelProperty
2. Checks if the alternate type is an external type (has identity property)
3. Reports a warning with code external-type-on-model-property
4. Returns early to prevent setting the invalid decorator data

Changes:

1. src/lib.ts: Added new diagnostic message "external-type-on-model-property"
2. src/decorators.ts: Added validation check in $alternateType decorator before processing external types
3. test/decorators/alternate-type.test.ts: Added test case to verify the warning is correctly reported
4. .chronus/changes/: Added changelog entry
5. lib/decorators.tsp: Updated decorator documentation with important note and invalid/valid examples
6. website/.../decorators.md: Updated generated documentation in website

Test: Added test case should warn when external type is applied to model property that verifies:

• The diagnostic is raised when external type info is used on a model property
• The diagnostic code is external-type-on-model-property

Documentation Updates:

• Added Important note stating external types cannot be applied to model properties
• Added example showing invalid usage with warning comment
• Added example showing correct usage (applying to type definition)

Note: External types should be applied to the type definition itself (Scalar, Model, Enum, or Union) instead of model properties, as shown in the existing external type tests.

Code Review: ✅ No issues found

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[TCGC] Check for external type</issue_title>
<issue_description>TCGC needs to report warning when @alternateType with external type info is decorated on model property. See playground here.

@@alternateType(FieldWithExternalType.name,
  {
    identity: "crate::models::HandWrittenType",
  },
  "rust"
);

The above usage could not work. TCGC needs to report warning.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [TCGC] Check for external type #3783

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/Azure/typespec-azure/@azure-tools/typespec-client-generator-core@3784

commit: 4fa225b

[tadelesh]

@copilot Please also update the doc for this decorator and use pnpm run regen-docs to regen the decorator doc in website.

[Copilot]

@copilot Please also update the doc for this decorator and use pnpm run regen-docs to regen the decorator doc in website.

Updated the decorator documentation in both lib/decorators.tsp and the website. Added an important note about external types not being applicable to model properties, along with an example showing invalid usage and the correct approach. Commit: bf49d66