refactor(compiler-cli): improve diagnostic with help link

[splincode]

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our guidelines: https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md
• [x] Tests for the changes have been added (for bug fixes / features)
• [x] Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• [ ] Bugfix
• [ ] Feature
• [ ] Code style update (formatting, local variables)
• [x] Refactoring (no functional changes, no api changes)
• [ ] Build related changes
• [ ] CI related changes
• [ ] Documentation content changes
• [ ] angular.dev application / infrastructure changes
• [ ] Other... Please describe:

What is the new behavior?

Fixes https://github.com/angular/angular/issues/45033

This PR enhances Angular's extended diagnostics by adding documentation links to error messages, improving the developer experience when encountering template errors.

Benefits

• Faster Problem Resolution: Developers can immediately access detailed explanations and examples

• Self-Documenting Errors: Reduces the need to search external documentation

• Consistent Experience: All extended diagnostics now provide uniform help resources

• Educational Value: Helps developers understand Angular best practices

Impact

• No breaking changes: Only enhances error messages

• No performance impact: Changes are compile-time only

• Improved DX: Better onboarding for developers learning Angular templates

Testing

• Verified that diagnostic messages display correctly with new links

• Confirmed that existing error examples and formatting are preserved

• Ensured links point to valid Angular documentation URLs

Does this PR introduce a breaking change?

• [ ] Yes
• [x] No

[JeanMeche]

Can you also please add that it fixes #45033.

[JeanMeche]

To fix the scope of the commit message should be compiler-cli instead of angular-cli. Also if we make it a refactor(compiler-cli) instead of a feat(compiler-cli) we could land this improvement in a patc release. (feat commits can only land in the next major/minor release).

[JeanMeche]

Also this change breaks some test, can you PTAL.

[SkyZeroZx]

Looks interesting. Could the same idea be considered for the rest of the Error Encyclopedia errors? https://angular.dev/errors It would be good to have the diagnostics sent to us in the reference documentation, like the Circular Dependency in DI case. https://angular.dev/errors/NG0200.

Although I think it would be a PR with several commits on a PR to add it, I don't know what the team would think.

[JeanMeche]

Looks interesting. Could the same idea be considered for the rest of the Error Encyclopedia errors?

We're already doing this for runtime errors (but only if the error actually has a doc entry. Those error are marked by a negative value)

example: https://github.com/angular/angular/blob/e34776a102cb83f22f3410fdf61de73a9f84b920/packages/core/src/errors.ts#L49-L51

[SkyZeroZx]

We're already doing this for runtime errors (but only if the error actually has a doc entry. Those error are marked by a negative value)

hadn’t noticed that the runtime errors were already being referenced. So, are there any plans to include the remaining ones as well?

From what I see, for example, NG2009 belongs to the common package range according to the comment:

 * Error code ranges per package:
 *  - core : 100-999
 *  - forms: 1000-1999
 *  - common: 2000-2999
 *  - animations: 3000-3999
 *  - router: 4000-4999
 *  - platform-browser: 5000-5500
 */

[JeanMeche]

That looks to be a bug in how we generate the error page. That's not a runtime error but a compiler error. Probably an issue introduced by #59355.

[JeanMeche]

Can you file an issue for that. On Angular.io we had a distinction between both type of errors. https://v17.angular.io/errors

[JeanMeche]

Can you have a look at the failing tests ? Some expect to match the exact error message. Also the lint check expects a body message of 20+ characters.

[JeanMeche]

Can you please rebase on main, it should fix the remaining broken test.

[splincode]

@JeanMeche Hello, is there anything else I should do?

[JeanMeche]

This change requires a cleanup on our side in Google's code base for us to be able to land it. We'll do it in due time aligned with our priorities.

[splincode]

@JeanMeche Thank you very much