♻️ Move needs_statuses and need_tags checking to schema validation

[chrisjsewell]

This PR refactors needs_statuses and needs_tags checking, from explicit validation logic (at need creation time) to the new generic schema-based validation system.
The changes rename extra_option schema validation to option validation (covering both core and extra options) and automatically generate schema constraints from the needs_statuses and needs_tags configuration, for example:

• needs_statuses = ["a", "b"] to {"status": {"type": "string", "enum": ["a", "b"]}} and
• needs_tags = ["a", "b"] to {"tags": {"type": array", "items": {"type": "string", "enum": ["a", "b"]}}}

This fixes issues with these being evaluated too early and not accounting for dynamic functions, needextend, etc ...
and will also facilitate #1547

[Copilot]

Pull request overview

This PR refactors schema validation by moving needs_statuses and needs_tags checking from explicit validation logic to JSON schema-based validation. The changes rename extra_option schema validation to option validation (covering both core and extra options) and automatically generate schema constraints from the needs_statuses and needs_tags configuration.

Key changes:

• Removed manual validation checks for needs_statuses and needs_tags in favor of schema-based validation
• Renamed validate_extra_options to validate_option_fields and expanded scope to include core fields
• Updated schema generation to automatically inject enum constraints for status and tags fields

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_broken_docs.py	Updated test assertions to reflect new schema validation error format for status and tags violations
tests/schema/snapshots/test_schema.ambr	Updated snapshot test expectations to reflect renamed validation paths and subtypes
sphinx_needs/schema/process.py	Refactored to use validate_option_fields instead of validate_extra_options and include core fields in validation
sphinx_needs/schema/core.py	Renamed function and updated schema path/rule names from extra_option to option
sphinx_needs/schema/config.py	Renamed enum values from extra_option_* to option_* for consistency
sphinx_needs/needs.py	Added logic to merge needs_statuses and needs_tags config into field schemas as enum constraints
sphinx_needs/api/need.py	Removed explicit validation logic for status and tags that is now handled by schema validation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ubmarco]

LGTM. One comment, and I also see a Copilot message.

[ubmarco]

This makes SN more resilient, but the error also appears later in the build process, right?

[chrisjsewell]

It does appear later yes, but that it actually more "correct", since otherwise the validation is wrong, if e.g. the status is a dynamic function, etc.
It is of note that these warnings no longer include "source mapping" to the original need, this may be a consideration for all of these schema warnings?

[ubmarco]

Yes, that should totally be there, I thought about this before.
We know the affected need ID, so should not be too hard.

[chrisjsewell]

okie, well if you want to maybe open an issue for that, or do the PR yourself, but otherwise I just keep it in my internal todo list lol

[ubmarco]

Here we go #1606

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.15%. Comparing base (4e10030) to head (7ff7c80).
⚠️ Report is 216 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1605      +/-   ##
==========================================
+ Coverage   86.87%   88.15%   +1.27%     
==========================================
  Files          56       70      +14     
  Lines        6532     9685    +3153     
==========================================
+ Hits         5675     8538    +2863     
- Misses        857     1147     +290     

Flag	Coverage Δ
pytests	88.15% <100.00%> (+1.27%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.