feat(alerts): use the meta description in source freshness alerts

[dobsontom]

This PR uses a source's meta.description as the description in its source freshness alerts, and keeps the existing default where it isn't set. Test alerts already do this (TestAlertDataSchema.format_alert takes self.description or self.test_description), so SourceFreshnessAlertDataSchema now does the same.

I've added a parametrised test to tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py covering meta.description, meta.alerts_config.description, and the fallback. I've also added a source example to the alert description docs.

Closes #2396

Summary by CodeRabbit

• Bug Fixes

  • Source freshness alerts now use a configured description when available, falling back to the freshness description otherwise.

• Documentation

  • Clarified that descriptions can be configured for source freshness checks as well as tests, with a YAML example.

[github-actions]

👋 @dobsontom
Thank you for raising your pull request.
Please make sure to add tests and document all user-facing changes.
You can do this by editing the docs files in this pull request.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 8c26e9b8-4a56-4149-b4b9-545cd2407424

📥 Commits

Reviewing files that changed from the base of the PR and between 9c13ec1 and 6165afd.

📒 Files selected for processing: 3

• docs/_snippets/guides/alerts-code-configuration.mdx
• elementary/monitor/fetchers/alerts/schema/alert_data.py
• tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Source freshness alerts now use a configured description when one is present. Otherwise, they keep the default freshness description. The guide and tests cover this behavior.

Changes: Source Freshness Alert Descriptions

Layer / File(s)	Summary
Format and document source freshness descriptions elementary/monitor/fetchers/alerts/schema/alert_data.py, tests/unit/monitor/fetchers/alerts/schemas/test_alert_data_schema.py, docs/_snippets/guides/alerts-code-configuration.mdx	The formatter uses the shared alert description when present and falls back to the freshness description. Tests cover the fallback and descriptions from top-level or nested alerts_config metadata. The guide adds a source metadata example.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 6165a

Source-freshness alerts can use configured descriptions while retaining the existing default when unset. No material merge risk is evident.

Security architecture risk: ⚪ Minimal · up to 6165a

The change affects descriptive alert content while preserving the existing fallback. No material security risk was identified: alert status, destinations, permissions, and execution behavior remain unchanged in the reviewed flow.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated new influence is over source-freshness notification content for metadata-controlled resources, delivered through existing alert destinations. The inspected flow does not grant additional service, tenant, credential, or execution authority.

Trust Boundaries and Controls

• observed — Metadata-derived text reaches Slack rich-text presentation through the same message-construction and length-limiting path used for the previous description. This is presentation influence, not evidence of command execution or an authorization bypass; the existing rendering path is not a general sanitization guarantee.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Issue #2396 requires source freshness alerts to use meta.description or meta.alerts_config.description, with the existing default when neither is set. The reviewed change updates `SourceFreshnessA…
Out of Scope Changes check		The implementation changes source freshness alert description selection. The added tests verify the linked issue behavior, and the documentation example explains the new configuration. These changes s…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: source freshness alerts now use the meta description.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}