Validate hinted methods

[shihab-dls]

Closes #300

This PR validated hinted scan and command methods, and splits validation logic into helper functions.

Summary by CodeRabbit

• New Features

  • Enhanced method type-hint validation and binding support in controller configurations.
  • Comprehensive name clash detection across all component types including attributes, sub-controllers, commands, and scan methods.
  • Centralized validation framework for consistent error handling throughout initialization.

• Improvements

  • Improved validation error messages and logging for clearer diagnostic feedback on configuration issues.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request enhances BaseController with comprehensive validation support for type-hinted Method objects. It introduces centralized name-clash detection across attributes, methods, and sub-controllers, adds post-initialization validation for hinted methods, and expands the public API to expose Method for type-based hints.

Changes

Cohort / File(s)	Summary
Method Validation & Name Clash Detection src/fastcs/controllers/base_controller.py	Added support for tracking and validating type-hinted Method objects via new __hinted_methods mapping. Introduced centralized _check_for_name_clash method to detect naming conflicts across attributes, methods, and sub-controllers. Extended validation with helper methods _validate_hinted_member, _validate_hinted_method, and _validated_added_method to enforce presence and type correctness. Updated add_attribute, add_sub_controller, add_command, and add_scan to leverage new validation mechanisms.
API Export Expansion src/fastcs/methods/__init__.py	Re-exported Method from .method module to make it publicly available for type-hinting purposes.
Test Updates tests/test_controllers.py	Updated test assertions to reflect new validation error messages. Added parameterized testing for name-clash scenarios across attributes, sub-controllers, and methods. Introduced async test coverage for hinted method validation, including verification of introspection failures and conflict detection with commands and scans.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Poem

🐰 With whiskers twitching, we bind methods tight,
Type hints now dance in validation's light,
Name clashes caught before they take flight,
Controllers validated, everything's right! ✨

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 32.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Validate hinted methods' accurately summarizes the main change, which introduces validation for hinted method objects in the BaseController.
Linked Issues check	✅ Passed	The PR implements all acceptance criteria from issue #300: helper method _check_for_name_clash checks attributes/methods/sub-controllers for name clashes, hinted methods are validated post-initialization, and method assignment fails on name conflicts.
Out of Scope Changes check	✅ Passed	All changes are directly related to validating hinted methods and extracting validation helper functions. No unrelated changes detected beyond the stated objectives.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch validate_methods

---

No actionable comments were generated in the recent review. 🎉

---

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

[codecov]

Codecov Report

❌ Patch coverage is 96.42857% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.90%. Comparing base (5d6b41c) to head (ab37703).

Files with missing lines	Patch %	Lines
src/fastcs/controllers/base_controller.py	96.36%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #320      +/-   ##
==========================================
+ Coverage   90.84%   90.90%   +0.06%     
==========================================
  Files          70       70              
  Lines        2555     2594      +39     
==========================================
+ Hits         2321     2358      +37     
- Misses        234      236       +2     

☔ 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.