Refine documentation for clarity and consistency

[vickgoodman]

A bigger PR with small improvements/modifications to documentation/docstrings and other.

[Copilot]

Pull request overview

This PR primarily refines documentation and inline comments across the test suite and core check implementations, while also introducing a handful of small functional/typing changes (e.g., stricter typing, ABC base classes, and a bit more defensive module loading).

Changes:

• Clarifies and standardizes docstrings/comments/messages across tests, docs, and check implementations.
• Updates typing annotations to modern built-in generics/PEP 604 unions and adds a few small robustness tweaks (e.g., importlib spec validation).
• Makes some small internal API/utility adjustments (e.g., rename to get_beman_recommended_license_path, Git remote access refactor, and minor logging stream refactor).

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/utils/registry.py	Uses importlib.util and adds defensive checks when dynamically loading test modules.
tests/utils/path_runners.py	Docstring clarity improvements for test runners.
tests/lib/checks/system/test_registry.py	Improves comment wording and assertion message clarity.
tests/lib/checks/beman_standard/repository/test_repository.py	Tightens wording in docstrings/comments for repository checks tests.
tests/lib/checks/beman_standard/release/test_release.py	Docstring wording improvements for release checks tests.
tests/lib/checks/beman_standard/readme/test_readme.py	Improves comments/docstrings for README checks tests.
tests/lib/checks/beman_standard/file/test_file.py	Minor variable rename for readability in test logic.
tests/lib/checks/beman_standard/directory/test_directory.py	Docstrings updated to clearly state expected outcomes.
tests/conftest.py	Docstring wording improvement (“Set up …”).
README.md	Minor formatting and relative link tweaks.
docs/pre-commit.md	Minor wording improvement in configuration notes.
docs/dev-guide.md	Wording/capitalization tweaks and minor phrasing improvements.
beman_tidy/lib/utils/string.py	Docstring wording refinement.
beman_tidy/lib/utils/logger_config.py	Refactors stdout stream wrapper methods to staticmethods.
beman_tidy/lib/utils/git.py	Typing improvements and refactor of remote URL retrieval; function rename for “recommended” license path.
beman_tidy/lib/utils/comments.py	Docstring wording refinements.
beman_tidy/lib/pipeline.py	Comment cleanup and spelling (“color”).
beman_tidy/lib/checks/system/registry.py	Modernizes typing annotations (built-in generics / unions).
beman_tidy/lib/checks/beman_standard/repository.py	Comment wording improvements.
beman_tidy/lib/checks/beman_standard/release.py	Docstring wording cleanup (capitalization).
beman_tidy/lib/checks/beman_standard/readme.py	Makes base check explicitly abstract and tweaks skip message text.
beman_tidy/lib/checks/beman_standard/license.py	Makes base check explicitly abstract; updates renamed utility function import/use.
beman_tidy/lib/checks/beman_standard/file.py	Adds typing + converts some helpers to staticmethods; minor docstring improvements.
beman_tidy/lib/checks/beman_standard/directory.py	Makes base check explicitly abstract and significantly reformats a docstring example block.
beman_tidy/lib/checks/beman_standard/cpp.py	Converts helper to staticmethod.
beman_tidy/lib/checks/beman_standard/cmake.py	Adds typing imports, stronger AST node checks, and annotates parse methods; makes base check abstract.
beman_tidy/lib/checks/base/file_base_check.py	Adds type annotations and minor internal readability improvements.
beman_tidy/lib/checks/base/base_check.py	Docstring wording/capitalization improvements and small formatting tweaks.
beman_tidy/.beman-standard.yaml	Comment wording tweak for clarity.

Comments suppressed due to low confidence (1)

beman_tidy/lib/utils/git.py:56

• The PR title suggests documentation-only changes, but this file includes functional behavior changes (e.g., updated typing for get_repo_info, different remote access via repo.remote(...), and related runtime behavior). Please update the PR title/description to reflect the non-doc changes (or split functional changes into a separate PR) so reviewers can assess risk appropriately.

def get_repo_info(path: str, config_path: str | None = None):
    """
    Get information about the repository at the given path.
    Returns data as a dictionary.
    """

---

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

[vickgoodman]

Done.

[vickgoodman]

It is intentional.

[vickgoodman]

Done.

[vickgoodman]

Done.

[vickgoodman]

Done.

[vickgoodman]

Done.