v1.6.3 - Fix Rich Markup Bug Hiding Bracket Notation in Type Annotations

Summary

This release fixes a critical bug where bracket notation in type annotations (e.g., list[str], dict[str, int], complex nested generics like list[dict[Literal["key"], list[number]]]) was being completely hidden from DFC error output due to Rich library's markup interpretation system treating square brackets as formatting tags. The fix implements Rich's escape() function to properly display bracket notation while preserving red colour formatting in error messages. Additionally, this release addresses a secondary quote normalisation bug that was causing false positive type mismatches between function signatures and docstrings due to inconsistent quote styles between Python's ast.unparse() output (single quotes) and typical docstring conventions (double quotes).

Release Statistics

Attribute	Note
Version:	[v1.6.3]
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (951 statements, +4 from v1.6.2)
Pylint Score:	10.00/10
Complexity:	All functions ≤13 threshold
Functions:	106 (unchanged from v1.6.2)
Tests Passing:	223/223 (+5 new bracket notation tests)
Files Changed:	3 (cli.py, core.py, test_core.py)
Lines Added:	285
Lines Removed:	4
Commits:	3
Pull Requests Merged:	1 (PR #24)

🐛 Critical Bug Fix: Rich Markup Interpretation

Overview

Fix a critical display bug where Rich library's markup interpretation system was treating square brackets in type annotations as formatting tags, causing them to be completely hidden from error output. This made error messages misleading and unhelpful, as developers couldn't see the actual type mismatches between function signatures and docstrings.

Problem Statement

Invisible Bracket Notation:

When validating functions with generic type annotations, DFC was displaying error messages that completely omitted bracket notation, making it appear that signature and docstring types matched when they clearly didn't.

Real-World Example:

Consider this function with a complex nested generic type:

def process_data(
    data: list[dict[Literal["coeff", "ts"], list[number]]] | None,
) -> None:
    """
    Process data.

    Params:
        data (list | None):
            The input data.
    """
    ...

The actual signature contains list[dict[Literal["coeff", "ts"], list[number]]], but the docstring only documents list. When DFC detected this mismatch, the error output showed:

$ dfc src/tests/time_series.py

Parameter type mismatch for 'data':
  - Signature: list | None
  - Docstring:  list | None

Both signature AND docstring were displaying as list instead of the full type! The error appeared to show matching types when they clearly didn't match, making it completely unhelpful for debugging.

Root Cause Analysis

Primary Bug: Rich Markup Interpretation

The Rich library (v13+) interprets square brackets [...] as markup/styling tags by default. When displaying list[number], Rich's markup parser sees:

• list → literal text to display
• [number] → potential markup tag
• Since [number] isn't a recognised formatting tag, Rich hides the content to prevent rendering errors

This behaviour is intentional in Rich for supporting inline formatting like [red]...[/red] for colour or [bold]...[/bold] for emphasis, but it causes bracket notation in type annotations to completely disappear from output.

Secondary Bug: Quote Style Normalisation

Python's ast.unparse() function consistently outputs type annotations using single quotes, regardless of the original source code:

import ast

# Even if source uses double quotes
annotation = ast.parse('list[dict[Literal["key"], int]]').body[0].annotation
ast.unparse(annotation)  # Returns: "list[dict[Literal['key'],int]]"

However, docstrings typically use double quotes as per PEP 257 conventions:

"""
Params:
    data (list[dict[Literal["key"], int]]):
        The data parameter.
"""

When comparing these strings directly without normalisation, DFC reported false positive type mismatches even when the types were semantically identical, simply due to quote style differences between ast.unparse() output and docstring content.

Solution Implementation

Fix 1: Rich Markup Escaping

Import and use Rich's escape() function to properly escape square brackets for display while keeping markup=True for colour rendering.

Files Modified:

• src/docstring_format_checker/cli.py (+11 lines, -2 lines)

Implementation Changes:

Import escape() Function

Add Rich's escape function to the imports:

from rich.markup import escape

Location: Line 55 in src/docstring_format_checker/cli.py

Escape Error Messages in _format_error_messages()

Wrap error messages with escape() before processing to prevent Rich from interpreting brackets as markup:

def _format_error_messages(error_message: str) -> str:
    """
    Format error messages for display.
    """
    # Escape square brackets for Rich markup using Rich's escape function
    error_message = escape(error_message)

    if "; " in error_message:
        # Split by semicolon and rejoin with proper formatting
        errors: list[str] = error_message.split("; ")
        # ... rest of method

Location: Line 360 in src/docstring_format_checker/cli.py

This ensures all error messages have their square brackets properly escaped before any formatting is applied, preventing Rich from interpreting [str], [number], etc. as markup tags.

Update Table Output with Inline Markup

Replace Text() objects with inline markup tags to apply red colour formatting while allowing escaped brackets to display correctly:

# Old approach (required markup=False):
table.add_row(
    file_path,
    str(error.line_number),
    error.item_name,
    error.item_type,
    formatted_error_message,  # Plain text
)

# New approach (uses inline markup with escaped content):
table.add_row(
    file_path,
    str(error.line_number),
    error.item_name,
    error.item_type,
    f"[red]{formatted_error_message}[/red]",  # Red colour applied via markup
)

Location: Line 489 in src/docstring_format_checker/cli.py

This change allows colour formatting to be applied through markup tags while the error message content itself has been safely escaped.

Escape Individual Errors in List Format

Apply escape() to each error in the list output format with explicit type hints:

def _format_error_output(error: DocstringError) -> list[str]:
    """
    Format error output for list display.
    """
    # ... earlier code ...
    
    for individual_error in individual_errors:
        # Escape square brackets for Rich markup using Rich's escape function
        individual_error: str = escape(individual_error)

        # Check if this error has multi-line content
        if "\n" in individual_error:
            # Split by newlines and add indentation
            error_lines: list[str] = individual_error.split("\n")
            # ... rest of method

Location: Line 552 in src/docstring_format_checker/cli.py

The explicit type hints (individual_error: str and error_lines: list[str]) improve code clarity and help with type checking.

Fix 2: Quote Normalisation in Type Comparison

Add quote normalisation to the _normalize_type_string() method to ensure consistent comparison regardless of quote style differences between ast.unparse() and docstrings.

Files Modified:

• src/docstring_format_checker/core.py (+7 lines, -2 lines)

Implementation:

Add quote normalisation after whitespace removal to convert all double quotes to single quotes:

def _normalize_type_string(self, type_str: str) -> str:
    """
    Normalize type string for comparison.
    """

    # Remove whitespace
    normalized: str = re.sub(r"\s+", "", type_str)

    # Normalize quotes: ast.unparse() uses single quotes but docstrings typically use double quotes
    # Convert all quotes to single quotes for consistent comparison
    normalized = normalized.replace('"', "'")

    # Make case-insensitive for basic types
    # But preserve case for complex types to avoid breaking things like Optional
    return normalized

Location: Line 1127 in src/docstring_format_checker/core.py

This ensures that list[dict[Literal["key"], int]] and list[dict[Literal['key'], int]] are treated as identical during type comparison, eliminating false positive mismatches caused purely by quote style differences.

Clean Up Formatting

Remove trailing space from parameter mismatch block formatting:

# Old (with trailing space):
param_block: str = f"""'{name}':\n    - signature: '{sig_type}'\n    - docstring: '{doc_type}' """

# New (no trailing space):
param_block: str = f"""'{name}':\n    - signature: '{sig_type}'\n    - docstring: '{doc_type}'"""

Location: Line 1223 in src/docstring_format_checker/core.py

Comprehensive Test Coverage

Add five...

v1.6.2 - Enhanced Parameter Validation Error Reporting

Summary

This release delivers significant improvements to parameter validation error reporting within the core docstring checker. The enhancement replaces the generic "Missing or invalid Params section" error with detailed diagnostics that precisely identify which parameters are missing from docstrings, which are incorrectly documented, or both directions of mismatch, dramatically reducing debugging time and improving developer experience during refactoring and code maintenance activities.

Release Statistics

Attribute	Note
Version:	[v1.6.2]
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (947 statements, +41 from [v1.6.1])
Pylint Score:	10.00/10
Complexity:	All functions ≤13 threshold
Functions:	106 (+3 validation methods)
Tests Passing:	223/223 (+17 from [v1.6.1])
Files Changed:	1 (core.py)
Lines Added:	111
Lines Removed:	3
Commits:	1
Pull Requests Merged:	1 (PR #23)

🎯 Parameter Validation Enhancement

Overview

Transform parameter validation from providing generic error messages into delivering precise, actionable diagnostics that immediately pinpoint parameter documentation issues. This enhancement significantly reduces debugging time by clearly identifying which parameters are missing from docstrings, which are incorrectly documented, or bidirectional mismatches, making it easier for developers to maintain accurate documentation during refactoring and code evolution.

Problem Statement

Misleading Generic Error Messages:

The previous parameter validation implementation provided only a generic error message when parameters in function signatures did not match those documented in docstrings:

Missing or invalid Params section

This error message was fundamentally misleading and created significant developer friction:

1. Ambiguous Root Cause: Could indicate either a completely missing Params section OR parameter mismatches between signature and documentation
2. No Actionable Information: Failed to specify which parameters were problematic or how they mismatched
3. Time-Consuming Debugging: Required developers to manually compare function signature against docstring to identify specific issues
4. Common During Refactoring: Parameter additions, removals, or renames during refactoring often left docstrings outdated without clear guidance
5. Typo Detection Impossible: Simple typos in parameter names (e.g., interpol_nodes vs interpolation_nodes) required manual detective work

Real-World Example:

Consider this function with a parameter mismatch:

def generate_fixed_error_index(
    time_series: pd.DataFrame,
    error_magnitude: float,
    seed: Optional[int] = None,
) -> pd.Series:
    """
    Generate fixed error index.

    Params:
        time_series (pd.DataFrame):
            The input time series data.
        error_magnitude (float):
            The magnitude of error to apply.
    """
    ...

Previous Error Output:

$ dfc src/tests/time_series.py

src/tests/time_series.py
  Line 45 - function 'generate_fixed_error_index':
    - Missing or invalid Params section

Developer Actions Required:

1. Open function in editor
2. Read function signature → identify 3 parameters
3. Read docstring Params section → identify 2 documented parameters
4. Manually compare lists → realise seed parameter is missing
5. Update docstring to document seed parameter

This manual process was tedious, error-prone, and particularly problematic in large codebases with hundreds of functions requiring documentation updates during refactoring initiatives.

Solution Architecture

Implement a three-method validation system that extracts documented parameters from docstrings, compares them against function signatures, and constructs detailed error messages describing exact mismatches in both directions.

Files Modified:

• src/docstring_format_checker/core.py (+114 lines, -3 lines)
• src/tests/test_core.py (+408 lines)

Core Implementation

New Method: _extract_documented_params()

Extract parameter names from the Params section of a docstring using regex pattern matching and state machine logic.

Implementation:

def _extract_documented_params(self, docstring: str) -> list[str]:
    """
    Extract parameter names from the Params section of a docstring.
    """
    documented_params: list[str] = []
    param_pattern: str = r"^\s*(\w+)\s*\([^)]+\):"
    lines: list[str] = docstring.split("\n")
    in_params_section: bool = False

    for line in lines:
        # Check if we've entered the Params section
        if "Params:" in line:
            in_params_section = True
            continue

        # Check if we've left the Params section (next section starts)
        if in_params_section and re.match(r"^[ ]{0,4}[A-Z]\w+:", line):
            break

        # Extract parameter name
        if in_params_section:
            match = re.match(param_pattern, line)
            if match:
                documented_params.append(match.group(1))

    return documented_params

Functionality:

1. Section Detection: Identify when entering the Params section by matching "Params:" text in lines
2. Boundary Recognition: Detect when leaving Params section by matching new section headers (capitalised words followed by colon with ≤4 spaces indentation)
3. Parameter Extraction: Use regex pattern ^\s*(\w+)\s*\([^)]+\): to capture parameter names from lines like name (str): or age (int):
4. State Management: Track whether currently parsing within Params section using boolean flag to ensure accurate extraction

Benefits:

• Isolate parameter parsing logic into single, focused, testable method
• Handle multi-line parameter documentation correctly by only capturing parameter declaration lines
• Support various indentation styles and formatting variations across different docstring conventions
• Enable reuse across multiple validation scenarios without code duplication

New Method: _build_param_mismatch_error()

Construct detailed, formatted error messages that clearly communicate parameter mismatches in both directions with proper indentation and formatting.

Implementation:

def _build_param_mismatch_error(
    self,
    missing_in_docstring: list[str],
    extra_in_docstring: list[str],
) -> str:
    """
    Build detailed error message for parameter mismatches.
    """
    error_parts: list[str] = []

    if missing_in_docstring:
        missing_str: str = "', '".join(missing_in_docstring)
        error_parts.append(f"  - In signature but not in docstring: '{missing_str}'")

    if extra_in_docstring:
        extra_str: str = "', '".join(extra_in_docstring)
        error_parts.append(f"  - In docstring but not in signature: '{extra_str}'")

    return "Parameter mismatch:\n" + "\n".join(error_parts)

Message Format Examples:

Missing Parameters:

Parameter mismatch:
  - In signature but not in docstring: 'seed'

Extra Parameters:

Parameter mismatch:
  - In docstring but not in signature: 'city'

Bidirectional Mismatch:

Parameter mismatch:
  - In signature but not in docstring: 'email'
  - In docstring but not in signature: 'city'

Multiple Missing Parameters:

Parameter mismatch:
  - In signature but not in docstring: 'city', 'country'

Typo Detection:

Parameter mismatch:
  - In signature but not in docstring: 'interpolation_nodes'
  - In docstring but not in signature: 'interpol_nodes'

Benefits:

• Crystal Clear Diagnostics: Immediately identify exact nature of parameter mismatch without manual comparison
• Bidirectional Analysis: Show both missing and extra parameters simultaneously for complete picture
• Multiple Parameter Support: Handle cases where several parameters are mismatched in either direction
• Typo Detection: Bidirectional display makes typos immediately obvious (e.g., interpol_nodes vs interpolation_nodes)
• Consistent Formatting: Use bullet points, indentation, and quoted parameter names for enhanced readability

New Method: _check_params_section_detailed()

Orchestrate comprehensive parameter validation with detailed error reporting, replacing the boolean-only validation with rich diagnostic information.

Implementation:

def _check_params_section_detailed(
    self,
    docstring: str,
    node: Union[ast.FunctionDef, ast.AsyncFunctionDef],
) -> tuple[bool, Optional[str]]:
    """
    Check if the Params section exists and documents all parameters,
    with detailed error reporting.
    """
    # Get function parameters (excluding 'self' and 'cls' for methods)
    signature_params: list[str] = [
        arg.arg for arg in node.args.args if arg.arg not in ("self", "cls")
    ]

    if not signature_params:
        return (True, None)  # No parameters to document

    # Check if Params section exists
    if not re.search(r"Params:", docstring):
       ...

v1.6.1 - Refactor Validation Architecture and Fix Parser Bug

Summary

This release refactors the core docstring validation architecture to separate required section presence validation from section content validation, eliminate redundant code, and enhance error message formatting. The restructuring introduces a two-phase validation approach that first checks for required section presence, then validates content of all existing sections, eliminating false positives and improving maintainability. The release also fixes a critical parser bug where deeply indented lines containing capitalised words followed by colons (such as Default: lines in parameter descriptions) were incorrectly identified as section headers, causing the parser to prematurely exit the params section and fail to extract type information for subsequent parameters. Additionally, multi-line error formatting has been enhanced to properly indent continuation lines, significantly improving readability for complex validation failures such as parameter type mismatches. All changes maintain 100% test coverage and backwards compatibility, with 206/206 tests passing and no breaking changes to existing configurations or APIs.

Release Statistics

Attribute	Note
Version:	v1.6.1
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (906 statements, +9 from v1.6.0)
Pylint Score:	10.00/10
Complexity:	All functions ≤13 threshold
Functions:	103 (+3 new, -4 removed, +1 renamed)
Tests Passing:	206/206 (+7 new, -1 removed)
Files Changed:	5
Lines Added:	534
Lines Removed:	244
Commits:	8
Pull Requests Merged:	1 (PR #22)

🏗️ Validation Architecture Refactoring

Overview

Restructure the docstring validation logic into two distinct phases that separate required section presence checking from section content validation. This refactoring eliminates false positives where content validation was attempted on non-existent sections, reduces code duplication by consolidating four redundant helper methods into a single unified implementation, and improves extensibility for future enhancements requiring optional section content validation.

Problem Statement

Coupled Validation Logic:

The previous validation architecture combined section presence checking with content validation in a single pass through required sections. This coupling created several critical issues:

1. False Positives: Content validation attempted on sections that might not exist, generating confusing error messages
2. Code Duplication: Similar validation logic repeated across multiple helper methods (_check_returns_section(), _check_raises_section(), _check_yields_section(), _check_simple_section())
3. Unclear Responsibility: Methods named "validate" sometimes only checked existence without validating content
4. Maintenance Burden: Changes to validation logic required updates across multiple similar methods
5. Limited Flexibility: Optional sections with content validation requirements couldn't be easily supported

Example Issue:

When a required section was missing, validation would:

1. Check if section exists → No
2. Attempt to validate section content → Fails with unclear error
3. Report both "missing section" and "invalid content" errors

This created confusing error messages and made debugging difficult for users.

Solution Architecture

Implement a two-phase validation approach that cleanly separates concerns into distinct responsibilities:

Phase 1: Required Section Presence Validation

• Use _validate_all_required_sections() to check only that required sections exist
• Generate clear "Missing required section: {name}" errors when sections absent
• Apply special handling for params section based on function parameters

Phase 2: Existing Section Content Validation

• Use _validate_all_existing_sections() to validate content of all present sections
• Apply to both required and optional sections that exist in docstring
• Only validate sections that actually exist, avoiding false positive errors

Core Implementation

Refactor the _check_docstring() method to implement the two-phase validation approach with clear separation of concerns.

Files Modified:

• src/docstring_format_checker/core.py (+253 lines, -251 lines)

Method Restructure in _check_docstring()

Replace the single-phase validation with distinct phases:

# New approach (separated phases)
def _check_docstring(
    self, docstring: str, item: FunctionAndClassDetails
) -> Optional[DocstringError]:
    errors: list[str] = []

    # Phase 1: Validate required sections are present
    required_section_errors: list[str] = self._validate_all_required_sections(
        docstring, item
    )
    errors.extend(required_section_errors)

    # Phase 2: Validate all existing sections (required or not)
    existing_section_errors: list[str] = self._validate_all_existing_sections(
        docstring, item
    )
    errors.extend(existing_section_errors)

    # ... other validation

Benefits:

• Clear separation between presence and content validation
• Eliminates false positives from validating non-existent sections
• Enables optional section content validation
• Improves error message clarity and debugging

New Method: _is_params_section_required()

Extract params section requirement logic into dedicated method for improved code organisation and reusability:

def _is_params_section_required(self, item: FunctionAndClassDetails) -> bool:
    """
    Check if params section is required for this item.
    """

    # For classes, params section not required (attributes handled differently)
    if isinstance(item.node, ast.ClassDef):
        return False

    # For functions, only required if function has parameters (excluding self/cls)
    params = [arg.arg for arg in item.node.args.args if arg.arg not in ("self", "cls")]
    return len(params) > 0

Benefits:

• Centralise params requirement logic in one location
• Make params validation rules explicit and testable
• Reduce code duplication across validation methods
• Enable consistent params section handling throughout codebase

Refactored Method: _validate_all_required_sections()

Simplify to focus solely on presence validation, delegating content validation to phase 2:

def _validate_all_required_sections(
    self, docstring: str, item: FunctionAndClassDetails
) -> list[str]:
    """
    Validate all required sections are present.
    """

    errors: list[str] = []
    for section in self.required_sections:
        # Special handling for params section
        if section.name.lower() == "params":
            if not self._is_params_section_required(item):
                continue

        # Only check if the section exists, don't validate content yet
        if not self._section_exists(docstring, section):
            errors.append(f"Missing required section: {section.name}")
    return errors

Changes:

• Remove content validation logic (moved to phase 2)
• Use new _is_params_section_required() helper method
• Return lowercase section names in error messages for consistency
• Simplified error message format

New Method: _validate_all_existing_sections()

Introduce new method to validate content of all existing sections, regardless of whether they are required:

def _validate_all_existing_sections(
    self, docstring: str, item: FunctionAndClassDetails
) -> list[str]:
    """
    Validate content of all existing sections (required or not).
    """

    errors: list[str] = []
    for section in self.config.sections:
        # Only validate if the section actually exists in the docstring
        if self._section_exists(docstring, section):
            section_error = self._validate_single_section_content(
                docstring, section, item
            )
            if section_error:
                errors.append(section_error)
    return errors

Benefits:

• Apply content validation to optional sections that are present
• Avoid attempting validation on non-existent sections
• Process all sections consistently using same validation pipeline
• Enable future enhancement for optional section content requirements

New Method: _section_exists()

Consolidate section existence checking logic into single unified method, replacing four redundant helper methods:

def _section_exists(self, docstring: str, section: SectionConfig) -> bool:
    """
    Check if a section exists in the docstring.
    """

    section_name: str = section.name.lower()

    # For free text sections, use existing logic
    if section.type == "free_text":
        return self._check_free_text_section(docstring, section)

    # Check for admonition style sections
    if section.admonition and isinstance(section.admonition, str):
        if section.prefix and isinstance(section.prefix, str):
            pattern: str = (
                rf"{re.escape(section.prefix)}\s+{re.escape(section.admonition)}"
            )
            if re.search(pattern, docstring, re.IGNOREC...

v1.6.0 - Introduce Parameter Type Validation

Summary

This release introduces a major new feature: comprehensive parameter type validation that ensures consistency between function signature type annotations and docstring parameter documentation. The validation system proactively detects inconsistencies where developers modify function signatures without updating corresponding documentation, preventing type information drift that can mislead API consumers and cause runtime errors. The feature is enabled by default but can be disabled via configuration for gradual adoption in legacy codebases. The implementation includes five specialised validation methods that extract, normalise, compare, and report type annotation mismatches, with support for complex types including Optional, Union, list[T], dict[K, V], and deeply nested generics. The release maintains perfect code quality standards with 100% test coverage (897 statements), Pylint score of 10.00/10, and includes 23 new comprehensive test cases covering all validation scenarios. All changes are backwards compatible, requiring no migration effort from existing users.

Release Statistics

Attribute	Note
Version:	[v1.6.0]
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (897 statements, +63 from v1.5.1)
Pylint Score:	10.00/10
Complexity:	All functions ≤13 threshold
Functions:	103 (+5 validation methods)
Tests Passing:	206/206 (+23 from v1.5.1)
Files Changed:	6
Lines Added:	1,366
Lines Removed:	26
Commits:	7
Pull Requests Merged:	1 (PR #21)

🔍 Parameter Type Validation Feature

Overview

Introduce a comprehensive type validation system that compares parameter type annotations in function signatures against their documented types in docstrings. This feature proactively detects inconsistencies where developers modify function signatures without updating corresponding documentation, preventing type information drift that can mislead API consumers and cause runtime errors.

Problem Statement

Documentation Drift During Refactoring:

When refactoring code, developers frequently update function signatures by:

• Adding type hints to previously untyped parameters
• Changing parameter types (e.g., str → Optional[str])
• Modifying complex types (e.g., list → list[str])

However, docstrings often lag behind these changes, creating inconsistencies between actual implementation and documentation. This causes:

• API Consumer Confusion: Users rely on docstring documentation but receive different types
• Type Checker Limitations: Tools like mypy validate signatures but not docstring accuracy
• Maintenance Burden: Manual review required to catch documentation drift
• Runtime Surprises: Functions accept types not mentioned in docstrings

Example Inconsistency:

def process_data(value: Optional[str], count: int = 10) -> list[str]:
    """
    Process data value.

    Params:
        value (str): Input value to process.  # ❌ Missing Optional
        count (float): Number of iterations.  # ❌ Wrong type (int vs float)

    Returns:
        (list): Processed results.            # ❌ Missing generic type
    """
    ...

Solution Architecture

Implement validation system comprising five coordinated methods in the DocstringChecker class that extract, normalise, compare, and report type annotation mismatches.

Configuration Integration

Add new global configuration flag enabling parameter type validation across all docstring checks.

Files Modified:

• pyproject.toml
• src/docstring_format_checker/config.py
• src/docstring_format_checker/cli.py

Configuration Changes:

pyproject.toml:

[tool.docstring_format_checker.global]
allow_undefined_sections = false
require_docstrings = true
check_private = true
+validate_param_types = true  # Enable parameter type validation

config.py - GlobalConfig dataclass:

@dataclass(frozen=True)
class GlobalConfig:
    allow_undefined_sections: bool = False
    require_docstrings: bool = True
    check_private: bool = False
    validate_param_types: bool = True  # New parameter: Enable parameter type validation

config.py - _parse_global_config() function:

return GlobalConfig(
    allow_undefined_sections=tool_config.get("allow_undefined_sections", False),
    require_docstrings=tool_config.get("require_docstrings", True),
    check_private=tool_config.get("check_private", False),
    validate_param_types=tool_config.get(
        "validate_param_types", True
    ),  # New parameter: Enable parameter type validation
)

cli.py - Configuration example display:

allow_undefined_sections = false
require_docstrings = true
check_private = true
validate_param_types = true  # New parameter: Enable parameter type validation

Configuration Behaviour:

• Default: True (validation enabled by default)
• Rationale: Type consistency is critical for API reliability; opt-out model ensures maximum benefit
• Override: Set to false in pyproject.toml to disable validation
• Scope: Applies globally to all checked Python files when enabled

Core Implementation

Implement type validation through five specialised methods integrated into the existing validation pipeline.

Files Modified:

• src/docstring_format_checker/core.py (+190 lines)

Method 1: _extract_param_types()

Extract parameter type annotations from function AST nodes using Python's ast module.

Purpose: Parse function signature to obtain ground truth type information.

Implementation Highlights:

def _extract_param_types(
    self,
    node: Union[ast.FunctionDef, ast.AsyncFunctionDef],
) -> dict[str, str]:
    """
    Extract parameter names and their type annotations from function signature.
    """

    param_types: dict[str, str] = {}

    for arg in node.args.args:
        # Skip 'self' and 'cls' parameters
        if arg.arg in ("self", "cls"):
            continue

        # Extract type annotation if present
        if arg.annotation:
            type_str: str = ast.unparse(arg.annotation)
            param_types[arg.arg] = type_str

    return param_types

Key Features:

• AST Traversal: Iterate through function argument nodes
• Type Unparsing: Convert annotation AST back to string representation
• Special Parameters: Automatically skip self and cls (method context parameters)
• Missing Annotations: Omit parameters without type hints from result dictionary
• Complex Types: Handle Optional, Union, list[T], dict[K, V], and nested generics

Example Output:

# For: def func(self, name: str, items: list[int], flag: bool = True):
{"name": "str", "items": "list[int]", "flag": "bool"}
# Note: 'self' excluded, all annotations preserved exactly

Method 2: _extract_param_types_from_docstring()

Parse parameter types from docstring Params sections using regex pattern matching.

Purpose: Extract documented type information to compare against signature.

Key Features:

• Section Detection: Locate Params section within docstring structure
• Regex Parsing: Match name (type): pattern for parameter declarations
• Section Boundaries: Stop parsing when encountering next section (Returns, Raises, etc.)
• Whitespace Handling: Accommodate various indentation levels
• Complex Types: Preserve parentheses and brackets in type strings (Optional[str], Union[int, float])

Pattern Matching Examples:

# Matches:
"param1 (str):"  # → ("param1", "str")
"param2 (Optional[int]):"  # → ("param2", "Optional[int]")
"data (list[dict[str, Any]]):"  # → ("data", "list[dict[str, Any]]")

# Does not match (invalid format):
"param1: str"  # Missing parentheses
"param1 str:"  # Missing parentheses

Method 3: _normalize_type_string()

Standardise type string representations for consistent comparison.

Purpose: Remove formatting variations that don't affect semantic type equality.

Normalisation Operations:

• Whitespace Removal: Eliminate spaces around brackets, commas
  • list[ int ] → list[int]
  • Union[str , int] → Union[str,int]
• Case Preservation: Maintain original capitalisation for complex types
  • Optional[str] remains Optional[str] (not optional[str])
  • Allows case-insensitive comparison separately

Rationale:

• Formatting Independence: Accept equivalent types regardless of spacing conventions
• Complex Type Safety: Preserve capitalisation needed for typing module classes
• Comparison Reliability: Consistent normalisation ensures accurate matching

Method 4: _compare_param_types()

Compare normalised type strings between signature and docstring, identifying mismatches.

Purpose: Detect parameters where documented types differ from actual implementation.

Comparison Logic:

1. Iterate Signature Types: Check each parameter with type annotation
2. Skip Undocumented: Ignore parameter...

v1.5.1 - Stricter Code Quality Standards

Summary

This release strengthens code quality enforcement through stricter complexity thresholds and comprehensive import hygiene checks. Building upon the extensive refactoring work completed in [v1.5.0], this release reduces the maximum allowed cognitive complexity from 15 to 13, establishing proactive quality gates that prevent technical debt accumulation. The release also re-enables pycln checks in both linting and validation workflows, ensuring unused imports are automatically detected and removed throughout the development lifecycle. Additionally, complexity reporting verbosity has been optimised with the introduction of the details = "low" configuration option, reducing noise in CI/CD logs whilst maintaining actionable feedback. These enhancements maintain the codebase's excellent quality standards (100% test coverage, Pylint 10.00/10) whilst preventing regression of the refactoring achievements from [v1.5.0]. All changes are non-breaking and require no migration effort from users.

Release Statistics

Attribute	Note
Version:	[v1.5.1]
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (834 statements)
Pylint Score:	10.00/10
Complexity:	309 (max threshold now 13, was 15)
Functions:	98
Tests Passing:	183/183
Files Changed:	3
Lines Added:	3,119
Lines Removed:	185
Commits:	4
Pull Requests Merged:	1 (PR #20)

🎯 Stricter Complexity Threshold

Overview

Reduce the maximum allowed cognitive complexity threshold from 15 to 13 in the complexipy configuration, establishing stricter quality standards that preserve the refactoring achievements from [v1.5.0] and prevent future complexity regression.

Motivation

The comprehensive refactoring work completed in [v1.5.0] successfully eliminated all functions with complexity ≥15, reducing total cognitive complexity from 332 to 309 points (6.9% reduction). The current codebase distribution demonstrates excellent quality:

• 0 functions with complexity ≥15 (all eliminated through refactoring)
• 1 function with complexity 13 (_extract_items - justified Visitor Pattern implementation)
• 4 functions with complexity 10-12 (all documented and justified)
• 93+ functions with complexity ≤9 (excellent maintainability)

With all high-complexity functions eliminated, maintaining a threshold of 15 would allow gradual complexity creep back toward problematic levels. Reducing the threshold to 13 establishes a proactive quality gate that:

1. Prevents Complexity Regression: Catches functions approaching the 15+ range before they become maintenance burdens
2. Maintains Current Quality Baseline: All existing functions pass the 13 threshold, so no immediate refactoring required
3. Encourages Best Practices: Developers receive early warnings at complexity 13, prompting consideration of Extract Method and other refactoring patterns
4. Aligns with Industry Standards: Industry guidance suggests complexity 10-15 as "moderate" - setting threshold at 13 keeps code in the simpler half of this range

Implementation Details

Files Modified:

• pyproject.toml

Configuration Changes:

[tool.complexipy]
paths = "src/docstring_format_checker"
-max-complexity-allowed = 15
+max-complexity-allowed = 13
quiet = false
ignore-complexity = false
sort = "asc"

Technical Benefits

Proactive Quality Management:

• Automated checks prevent introduction of complex code before it reaches the main branch
• Pull requests exceeding complexity 13 are blocked until refactored
• Continuous monitoring ensures quality standards maintained across all contributions

Data-Driven Development:

• Objective metrics enable data-driven decisions about refactoring priorities
• Quantitative complexity scores provide discussion anchors during code review
• Removes subjectivity from "this code feels complex" assessments

Developer Guidance:

• Clear complexity targets guide development practices and code structure
• Early warnings at complexity 13 encourage proactive simplification
• Establishes shared understanding of acceptable complexity levels across team

Impact on Development Workflow

CI/CD Pipeline:

# Automated complexity checks now enforce threshold of 13
# Functions with complexity >13 fail the build
✗ Complexity check failed: function 'example()' has complexity 14 (max: 13)

Local Development:

# Run complexity check locally
uv run check-complexity

# Output shows functions approaching threshold
# Functions with complexity 10-13 appear with metrics
# Functions with complexity >13 trigger failures

Code Review:

• Reviewers see objective complexity metrics in PR status checks
• Complexity scores visible before detailed review begins
• Enables focused discussion on specific functions exceeding thresholds

🧹 Import Hygiene Re-enablement

Overview

Re-enable pycln checks in both the lint() and check() functions, ensuring unused imports are automatically detected and removed throughout the development lifecycle. This re-enablement follows resolution of Python 3.14 compatibility issues that previously required temporary disabling.

Background

The pycln tool was temporarily disabled in both linting and validation workflows due to compatibility issues with Python 3.14. Comments in the code indicated:

# check_pycln()  # <-- pycln is currently incompatible with python 3.14

Recent dependency updates or compatibility fixes have resolved this issue, enabling safe re-enablement across all supported Python versions (3.9-3.14).

Implementation Details

Files Modified:

• src/utils/scripts.py

Changes in lint() function:

def lint() -> None:
    run_black()
    run_blacken_docs()
    run_isort()
-   # run_pycln()
+   run_pycln()

Changes in check() function:

def check() -> None:
    check_black()
    check_blacken_docs()
    check_mypy()
    check_isort()
    check_codespell()
-   # check_pycln()  # <-- pycln is currently incompatible with python 3.14
+   check_pycln()
    check_pylint()
    check_complexity()
    check_docstrings()
    check_pytest()
    check_mkdocs()
    check_build()

What is pycln?

pycln is a formatter for finding and removing unused import statements in Python code. It performs static analysis to identify imports that are never referenced in the module, then safely removes them to improve code cleanliness and reduce cognitive load when reading import sections.

Dual Integration Points

1. Automated Cleanup via lint():

• Runs run_pycln() during code formatting workflow
• Automatically removes unused imports when developers run uv run lint
• Executes alongside black and isort for comprehensive code formatting
• Enables developers to clean up imports before committing changes

2. Validation via check():

• Runs check_pycln() during comprehensive quality validation
• Verifies no unused imports exist in the codebase
• Fails CI/CD pipeline if unused imports detected
• Provides specific error messages identifying which imports to remove
• Ensures all code in main branch maintains import hygiene

Technical Benefits

Code Quality Improvements:

• Cleaner Import Sections: Automatically remove unused import statements, reducing clutter
• Reduced Cognitive Load: Shorter import lists easier to understand and maintain
• Dependency Hygiene: Prevent accumulation of unnecessary import dependencies
• Consistent Standards: Enforce import cleanliness across entire codebase

Developer Experience Enhancements:

• Automated Cleanup: Developers don't manually track which imports are unused
• Pre-commit Safety: Running lint() cleans up imports before commits
• CI/CD Validation: Automated checks catch any missed unused imports
• Clear Error Messages: Specific feedback identifies exactly which imports to remove

Maintainability Benefits:

• Reduced Noise: Fewer imports means easier code navigation
• Faster Comprehension: Developers quickly identify actual dependencies
• Simpler Refactoring: Unused imports don't confuse refactoring efforts
• Better IDE Performance: Fewer imports reduce IDE analysis overhead

Usage Examples

Local Development Workflow:

# Run linting to automatically remove unused imports
uv run lint

# Runs black, blacken-docs, isort, and pycln
# Unused imports automatically removed from all files

Validation Workflow:

# Run comprehensive quality checks
uv run check

# Validates no unused imports exist
# Fails if any unused imports detected

What Gets Cleaned:

# Before: Module with unused imports
import sys          # ← unused
import os           # ← unused
from typing import Dict, List, Optional  # ← Optional unused
from pathlib import Path

def process_file(path: str) -> Dict[str, List[str]]:
    p = Path(path)
    return {"file": [str(p)]}

# Aft...

v1.5.0 - Add Complexity Monitoring & Comprehensive Code Refactoring

Summary

This release represents a major advancement in code quality, maintainability, and tooling integration for the Docstring Format Checker package. The release introduces automated complexity monitoring through complexipy integration, enabling continuous tracking of code complexity metrics throughout development. Major refactoring efforts have reduced total cognitive complexity by 6.9% (from 332 to 309 points) whilst expanding the codebase with 24 new focused helper methods, all whilst maintaining 100% test coverage across 834 statements and a perfect Pylint score of 10.00/10. The refactoring work has eliminated all functions with complexity ≥15, extracting complex logic into single-responsibility helper methods that improve readability and maintainability. Enhanced CI/CD workflows now run with increased parallelism, reducing build times and improving developer productivity. Comprehensive documentation improvements include complete docstring coverage for all 37 previously undocumented helper methods, ensuring consistent documentation standards throughout the codebase. These improvements establish a robust foundation for future development whilst maintaining backward compatibility with existing implementations.

Release Statistics

Attribute	Note
Version:	v1.5.0
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (834 statements)
Pylint Score:	10.00/10
Complexity:	309 (reduced from 332, -6.9%)
Functions:	98 (increased from 74, +24 helpers)
Tests Passing:	183/183
Files Changed:	7
Lines Added:	992
Lines Removed:	228
Commits:	5

📊 Complexity Monitoring Integration

Overview

This release integrates complexipy as an automated complexity monitoring tool, enabling continuous tracking of cognitive complexity metrics throughout the development lifecycle. The integration provides actionable insights into code complexity trends, helping maintainers identify refactoring opportunities and prevent complexity regression.

Implementation Details

The complexipy integration includes:

• Configuration in pyproject.toml: Added comprehensive complexipy configuration section with customised settings:

  [tool.complexipy]
  paths = ["src/docstring_format_checker"]
  exclude = ["__pycache__", "*.pyc"]
  max-complexity-allowed = 15
  quiet = false
  sort = "asc"

• CI/CD Integration: Automated complexity checks run in GitHub Actions workflows, validating complexity thresholds on every pull request and commit.

• Local Development Workflow: Developers can run complexity analysis locally using simplified commands:

  # Run complexity analysis
  uv run complexipy src/docstring_format_checker
  
  # Check compliance with thresholds
  uv run check-complexity

• Complexity Reporting: Generates detailed reports showing cognitive complexity for all functions, sorted by complexity score, enabling prioritised refactoring efforts.

Technical Benefits

• Proactive Complexity Management: Automated checks prevent introduction of overly complex code before it reaches the main branch, maintaining codebase quality standards.

• Objective Refactoring Priorities: Quantitative complexity metrics enable data-driven decisions about which functions require refactoring attention, eliminating subjective assessments.

• Continuous Quality Monitoring: Integration with CI/CD pipelines ensures complexity standards are maintained across all contributions, preventing technical debt accumulation.

• Developer Visibility: Real-time complexity feedback during development helps developers write cleaner, more maintainable code from the outset.

Complexity Achievements

The initial complexity analysis and subsequent refactoring efforts have achieved:

• Total Complexity Reduction: 332 → 309 points (6.9% reduction)
• High-Complexity Elimination: All functions with complexity ≥15 have been refactored
• Function Distribution: 98 total functions with 83+ functions having complexity ≤10
• Maintainability Improvement: Created 24 new focused helper methods with appropriate complexity levels

Usage Example

# Run complexity analysis with details
uv run complexipy src/docstring_format_checker --verbose

# Check against maximum threshold
uv run complexipy src/docstring_format_checker --max-complexity 15

# Generate sorted report
uv run complexipy src/docstring_format_checker --sort desc

🎨 CLI Error Display Refactoring

Overview

The CLI module has undergone comprehensive refactoring to improve error display formatting, message handling, and user experience. The refactoring effort focused on extracting display logic into single-responsibility helper methods, enhancing code readability and maintainability.

Refactoring Achievements

The CLI refactoring includes extraction of 13 new helper methods:

Display Formatting Methods:

• _count_errors_and_files() - Calculates total error count and affected file count from error dictionary
• _display_quiet_summary() - Displays minimal summary output in quiet mode
• _display_final_summary() - Displays comprehensive summary with error and file counts

Table Output Methods:

• _display_table_output() - Orchestrates table display for all errors with file paths and line numbers

List Output Methods:

• _display_list_output() - Orchestrates list display for all errors (complexity reduced from 13 → 6)
• _create_error_header() - Formats error header with file path and line number (complexity: 1)
• _split_error_messages() - Splits compound error messages on semicolon delimiter (complexity: 1)
• _format_error_output() - Orchestrates formatting of single error entry (complexity: 1)

Path Validation Methods:

• _validate_and_process_paths() - Validates and processes input paths from command-line arguments
• _process_all_paths() - Processes all paths and collects validation errors

Configuration Methods:

• _load_and_validate_config() - Orchestrates configuration loading with explicit or auto-discovery
• _load_explicit_config() - Loads explicitly specified configuration file
• _load_auto_discovered_config() - Auto-discovers configuration from project structure

Technical Impact

The refactoring delivers:

• Reduced Complexity: _display_list_output reduced from complexity 13 → 6 (54% reduction)
• Single Responsibility: Each helper method has one clear purpose, improving code comprehension
• Enhanced Testability: Smaller, focused methods are easier to unit test with precise assertions
• Improved Maintainability: Changes to specific display logic can be made in isolation without affecting other functionality
• Better Error Handling: Separation of validation and processing logic enables more precise error recovery

Code Example

# Before: Complex list output function
def _display_list_output(self, errors):
    for file_path, file_errors in sorted(errors.items()):
        for error_info in file_errors:
            line_number = error_info.get("line", "N/A")
            messages = error_info.get("message", "").split("; ")
            for msg in messages:
                print(f"{file_path}:{line_number}: {msg}")


# After: Orchestration with helper methods
def _display_list_output(self, errors):
    for file_path, file_errors in sorted(errors.items()):
        for error_info in file_errors:
            formatted_output = self._format_error_output(file_path, error_info)
            print(formatted_output)


def _format_error_output(self, file_path, error_info):
    header = self._create_error_header(file_path, error_info)
    messages = self._split_error_messages(error_info.get("message", ""))
    return f"{header}: {messages[0]}"

🔧 Core Module Refactoring

Overview

The core validation module has undergone extensive refactoring to reduce complexity, improve code organisation, and enhance maintainability. Seven major refactoring efforts have systematically extracted complex logic into focused helper methods, achieving a 6.9% reduction in total cognitive complexity.

Refactoring History

First Refactoring - _check_single_docstring:

• Complexity Reduction: 25 → 2 (92% reduction)
• Methods Extracted: 3 helper methods
  • _is_section_applicable_to_item (complexity: 9) - Section applicability checking
  • _get_applicable_required_sections (complexity: 4) - Required sections gathering
  • _handle_missing_docstring (complexity: 2) - Missing docstring handling

Second Refactoring - check_directory:

• Complexity Reduction: 23 → 8 (65% reduction)
• Methods Extracted: 3 helper methods
  • _should_exclude_file (complexity: 3) - Pattern matching for exclusions
  • _filter_python_files (complexity: 4) - File filtering logic
  • _check_file_with_error_handling (complexity: 1) - Error conversion

Third Refactoring - _check_colon_usage:

• Complexity Reduction: 19 → 0 (100% reduction - pure delegation)
• Methods Extracted: 4 helper methods
  • _validate_admonition_has_no_colon (complexity: 4) - Single admonition validation
  • `_check_admonition_colon_usag...

v1.4.0 - Add Python 3.14 Support & Add Enhanced Checks

Summary

This release represents a significant evolution of the Docstring Format Checker package, delivering comprehensive improvements across multiple dimensions of code quality, compatibility, and maintainability. The release introduces official Python 3.14 support, achieving complete cross-version compatibility from Python 3.11 through 3.14. Major enhancements include a complete code refactoring achieving 100% test coverage (783 statements), standardisation of type annotations throughout the codebase, and integration of advanced code quality tools including pylint and complexipy for static analysis and complexity monitoring. The release also delivers seamless pre-commit hook integration, enabling automated docstring validation in development workflows. Critical Windows encoding issues have been resolved, ensuring consistent behaviour across all operating systems. These improvements establish a robust foundation for future development whilst maintaining backward compatibility with existing implementations.

Release Statistics

Attribute	Note
Version:	v1.4.0
Python Support:	3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Test Coverage:	100% (783 statements)
Files Changed:	14
Lines Added:	2,918
Lines Removed:	403
Commits:	17

🐍 Python 3.14 Support

Overview

This release adds official support for Python 3.14, the latest Python version released in October 2024. The package now provides full compatibility across Python 3.11, 3.12, 3.13, and 3.14, ensuring users can leverage the latest Python features whilst maintaining support for earlier versions.

Implementation Details

The Python 3.14 support implementation includes:

• Updated GitHub Actions CI/CD workflows with Python 3.14 test matrix
• Verified compatibility with Python 3.14 standard library changes
• Validated all existing functionality against Python 3.14 runtime
• Updated package metadata in pyproject.toml to declare Python 3.14 support
• Comprehensive test execution across all supported Python versions

Technical Benefits

• Cross-Version Compatibility: The package maintains consistent behaviour across Python 3.11-3.14, allowing teams to upgrade Python versions without modifying their docstring validation configuration.
• Future-Proof Development: Early adoption of Python 3.14 ensures the package remains compatible with the latest language features and standard library improvements.
• Continuous Integration: Automated testing against all supported Python versions guarantees compatibility and prevents regression issues during development.

Usage Example

# Install with Python 3.14
python3.14 -m pip install docstring-format-checker

# Run with Python 3.14
python3.14 -m docstring_format_checker --check path/to/code

🔧 Code Refactoring and Architecture Improvements

Overview

The codebase has undergone comprehensive refactoring to improve maintainability, readability, and extensibility. This refactoring effort focused on modularising functionality, eliminating code duplication, standardising coding patterns, and enhancing error handling throughout the package.

Refactoring Achievements

• Modularisation: Core functionality has been reorganised into logical modules with clear separation of concerns. The cli.py, config.py, and core.py modules now follow single-responsibility principles, making the codebase easier to navigate and maintain.
• Code Deduplication: Identified and eliminated duplicate code patterns, consolidating common logic into reusable functions. This reduces maintenance burden and ensures consistent behaviour across the package.
• Enhanced Error Handling: Improved exception handling with custom exception classes in the utils/exceptions.py module. This provides more informative error messages and enables precise error recovery strategies.
• Documentation Improvements: Enhanced inline documentation and docstrings throughout the codebase, improving code comprehension for contributors and maintainers.

Technical Impact

The refactoring delivers:

• Reduced cyclomatic complexity in core functions
• Improved code navigation and IDE support
• Enhanced debugging capabilities through clearer stack traces
• Better alignment with Python best practices and PEP standards

🧪 100% Test Coverage Achievement

Overview

This release achieves complete test coverage with 100% code coverage across 783 statements in the core package. This milestone represents a comprehensive test suite that validates all code paths, edge cases, and error conditions throughout the package.

Testing Infrastructure

Coverage Statistics:

• Total Statements: 783
• Statements Covered: 783
• Coverage Percentage: 100%
• Test Framework: pytest
• Coverage Tool: coverage.py v7.11.0

Test Suite Expansion

The test suite has been significantly expanded with new test modules:

• test_config.py Enhancements: Added 133 lines of comprehensive configuration testing, validating:
  • Configuration file parsing and validation
  • Default configuration handling
  • Configuration override mechanisms
  • Invalid configuration error handling
  • Configuration merge strategies
• test_core.py Enhancements: Added 337 lines of core functionality testing, covering:
  • Docstring extraction and parsing
  • Format validation logic
  • Multi-style docstring support (Google, NumPy, Sphinx)
  • Error detection and reporting
  • Edge cases and boundary conditions
• test_cli.py Updates: Enhanced CLI testing to validate:
  • Command-line argument parsing
  • Exit code handling
  • Output formatting
  • Error message presentation

Quality Assurance Benefits

• Regression Prevention: Complete test coverage ensures that code changes cannot inadvertently break existing functionality without detection.
• Confidence in Refactoring: Developers can confidently refactor code knowing that the comprehensive test suite will catch any behavioural changes.
• Documentation Through Tests: The test suite serves as executable documentation, demonstrating expected behaviour for all package features.
• Continuous Quality Monitoring: Automated test execution in CI/CD pipelines maintains quality standards across all contributions.

Running the Test Suite

# Run full test suite with coverage
uv run pytest --config-file=pyproject.toml --cov-report=term-missing

# Run tests for specific module
uv run pytest src/tests/test_core.py

# Generate HTML coverage report
uv run pytest --config-file=pyproject.toml --cov-report=html

📋 Pylint Integration and Code Quality Standards

Overview

This release integrates pylint as a static analysis tool, establishing comprehensive code quality standards and automated linting checks. The pylint configuration enforces consistent coding style, detects potential bugs, and identifies code smells throughout the codebase.

Pylint Configuration

A comprehensive pylint configuration has been added to pyproject.toml, including:

• Enabled Checks:

  • Code style consistency (PEP 8 compliance)
  • Unused import detection
  • Variable naming conventions
  • Function complexity limits
  • Documentation completeness
  • Potential bug patterns

• Disabled Checks:

  • Selectively disabled checks that conflict with project-specific requirements or generate false positives in the codebase.

• Custom Settings:

  • Tailored scoring thresholds and error severity levels to match project quality standards.

Code Quality Improvements

The pylint integration has driven improvements in:

• Naming Conventions: Standardised variable, function, and class naming according to Python conventions.
• Import Organisation: Cleaned up import statements, removing unused imports and organising imports logically.
• Code Complexity: Refactored complex functions to reduce cyclomatic complexity and improve maintainability.
• Documentation Standards: Ensured all public functions, classes, and modules have appropriate docstrings.

Usage in Development Workflow

# Run pylint on entire codebase
pylint src/docstring_format_checker

# Run pylint with custom configuration
pylint --rcfile=pyproject.toml src/docstring_format_checker

# Check specific file
pylint src/docstring_format_checker/core.py

# Generate detailed report
pylint --output-format=text src/docstring_format_checker > pylint-report.txt

Integration with CI/CD

The pylint checks are integrated into the CI/CD pipeline, automatically validating code quality on every pull request and commit. This ensures that code quality standards are maintained consistently across all contributions.

🔗 Pre-Commit Hook Integration

Overview

This release introduces seamless integration with pre-commit hooks through a new .pre-commit-hooks.yaml configuration file. This enables automatic docstring validation before commits, preventing invalid docstrings from entering the codebase.

Pre-Commit Configuration

The .pre-commit-hooks.yaml file defines a hook for the Docstring Format Checker:

- id: docstring-format-checker
  name: Docstring Format Checker
  description: Validate Python docstring formats
  entry: docstring-format-checker
  language: python
  types: [python]

...

v1.3.0 - Enhance Development Workflow with Pre-commit Integration and Improved Documentation Generation

🎯 Summary

Introduce comprehensive development workflow enhancements that establish automated quality assurance and superior documentation generation capabilities. This release delivers significant improvements to the development pipeline through pre-commit hook integration, CI/CD workflow optimisation, and enhanced changelog generation with advanced type safety and formatting improvements.

Transform the development experience by implementing automated docstring validation through standardised pre-commit hooks whilst streamlining deployment processes and providing enhanced documentation generation. These enhancements establish robust quality gates that ensure consistent code standards across the codebase whilst improving developer productivity through automation and simplified tooling.

Key Enhancement Areas:

• Pre-commit Integration: Automated docstring validation through standardised pre-commit hooks for consistent code quality enforcement
• CI/CD Optimisation: Streamlined deployment workflows through UV package manager dependency removal and simplified tooling
• Enhanced Documentation: Superior changelog generation with stricter typing, improved formatting, and cleaner output presentation
• Type Safety Enhancement: Advanced Literal type hints for better IDE support and comprehensive static analysis capabilities
• Quality Automation: Integration of automated docstring format checking into standard development workflows

📈 Release Statistics

🔢 Code Changes Summary

• Files Modified: 4 core files with targeted workflow and documentation enhancements
• Lines Added: 1,500+ new lines including comprehensive changelog improvements and configuration updates
• Workflow Simplification: 11 lines removed from CI/CD workflow reducing external dependencies
• Pre-commit Integration: 6 new configuration lines enabling automated quality validation
• Type Safety: 5+ enhanced type annotations with Literal types for superior IDE support

📊 Development Experience Enhancement

• Automated Quality Gates: Pre-commit hooks providing immediate feedback on docstring formatting standards
• Simplified Dependencies: Reduced CI/CD complexity through standard Python tooling adoption
• Enhanced Documentation: Superior changelog formatting with improved readability and professional presentation
• Type Checking: Advanced static analysis support through comprehensive type hints and IDE integration

🛠️ Pre-commit Hook Integration

📋 Automated Quality Assurance Implementation

Establish comprehensive pre-commit integration supporting automated docstring validation:

• Hook Configuration: Introduce .pre-commit-hooks.yaml configuration enabling seamless integration with development workflows
• Python File Targeting: Configure regex pattern \.(py)$ ensuring comprehensive coverage of all Python source code files
• Entry Point Integration: Utilise docstring-format-checker command for consistent execution across development environments
• Quality Gate Enforcement: Prevent commits violating docstring formatting standards through automated pre-commit validation

Pre-commit Configuration:

# .pre-commit-hooks.yaml - Automated docstring validation
- id: docstring-format-checker
  name: docstring-format-checker  
  description: A CLI tool to check and format Python docstrings to adhere to specified style guidelines.
  entry: docstring-format-checker
  language: python
  files: '\.(py)$'

🔄 Development Workflow Enhancement

Enable seamless integration with established development practices:

• IDE Compatibility: Support integration with popular development environments utilising pre-commit hooks for automated quality checking
• Git Integration: Automatic execution during commit operations preventing commits that violate established docstring formatting standards
• CI/CD Compatibility: Compatible with continuous integration systems executing pre-commit hooks as automated testing pipeline components
• Developer Experience: Provide immediate feedback on formatting violations before code reaches repository for enhanced productivity

⚙️ CI/CD Workflow Optimisation

🚀 Deployment Pipeline Simplification

Streamline continuous deployment workflow through dependency reduction and tooling standardisation:

• UV Dependency Removal: Eliminate astral-sh/setup-uv@v6 action reducing external tool dependencies and potential deployment failure points
• Standard Python Setup: Utilise established actions/setup-python@v5 for reliable, well-supported Python environment configuration
• Simplified Installation: Replace UV-specific commands with standard pip install for enhanced compatibility and reduced complexity
• Maintained Functionality: Preserve essential installation flags whilst simplifying overall deployment workflow execution

Workflow Transformation:

# Before: UV-based installation with multiple setup dependencies
- name: Set up UV
  uses: astral-sh/setup-uv@v6
- name: Verify Python Version  
  run: |
    uv --version
    python --version
- name: Install Package
  run: uv pip install --no-cache --verbose "${{ env.PACKAGE_NAME }}==${{ env.VERSION }}"

# After: Simplified standard pip installation
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: ${{ matrix.python-version }}
- name: Install Package
  run: pip install --no-cache --verbose --no-python-version-warning "${{ env.PACKAGE_NAME }}==${{ env.VERSION }}"

🔧 Installation Process Enhancement

Improve deployment reliability and cross-platform compatibility:

• Standard Tooling: Utilise standard pip installation for consistent behaviour across operating systems and deployment environments
• Warning Suppression: Add --no-python-version-warning flag preventing unnecessary warning messages during installation processes
• Verbose Logging: Maintain --verbose flag ensuring comprehensive installation logging for debugging and monitoring capabilities
• Cache Management: Preserve --no-cache flag ensuring fresh package installations and avoiding potential caching-related deployment issues

📚 Enhanced Documentation Generation

🔤 Type Safety and IDE Support Enhancement

Implement comprehensive type hints for improved development experience and static analysis:

• Literal Type Annotations: Replace generic str types with Literal annotations for constants (OUTPUT_FILENAME, NEW_LINE, BLANK_LINE, LINE_BREAK, TAB) enhancing type safety
• Import Enhancement: Add Literal import from typing module supporting advanced type hinting and static analysis capabilities
• Static Analysis: Improve IDE support with enhanced type information enabling better code navigation, autocompletion, and refactoring
• Type Checking: Add strategic type: ignore comments for repository access ensuring compatibility with type checkers whilst maintaining functionality

Type Safety Implementation:

# Enhanced type safety with Literal annotations
from typing import Literal, Optional

OUTPUT_FILENAME: Literal["CHANGELOG.md"] = "CHANGELOG.md"
NEW_LINE: Literal["\n"] = "\n"  
BLANK_LINE: Literal["\n\n"] = "\n\n"
LINE_BREAK: Literal["<br>"] = "<br>"
TAB: Literal["    "] = "    "

📝 Commit Message Processing Enhancement

Improve changelog formatting through enhanced commit message processing and filtering:

• Co-authored Line Filtering: Remove "Co-authored-by" lines from commit messages focusing on primary commit content for improved readability
• Empty Line Handling: Filter out blank lines and whitespace-only content ensuring cleaner changelog presentation and professional formatting
• Message Structure: Restructure commit entry format with enhanced layout including short SHA and improved author attribution formatting
• Output Quality: Generate superior changelog output with consistent formatting, professional presentation, and enhanced navigation capabilities

Processing Logic Enhancement:

# Enhanced commit message processing with comprehensive filtering
commit_message_list: list[str] = []
for line in commit.commit.message.split(NEW_LINE):
    line_stripped: str = line.strip()
    # Filter out blank lines and "Co-authored-by" lines for cleaner output
    if line_stripped and not line_stripped.lower().startswith("co-authored-by:"):
        commit_message_list.append(line_stripped)

🏗️ Release Information Enhancement

Correct GitHub API property access and improve changelog structure consistency:

• Property Access Fix: Change from release.title to release.name ensuring correct GitHub API property access and accurate release information
• Title Formatting: Establish proper release title formatting in generated changelog documentation for structural consistency
• Metadata Accuracy: Provide accurate release metadata including correct title, date, and link information enhancing documentation quality
• Structure Consistency: Maintain uniform changelog structure across all release entries improving readability and professional presentation

🎯 Development Experience Enhancement

🛡️ Quality Assurance Automation

Establish comprehensive automated quality gates for consistent code standards:

• Pre-commit Validation: Automatic docstring format checking preventing formatting violations from entering repository codebase
• Consistent Standards: Enforce uniform docstring formatting standards across entire codebase through automated validation and immediate feedback
• Developer Feedback: Provide instant feedback on formatting violations during development workflow enabling rapid issue resolution
• **C...

v1.2.0 - Enhance CLI with Multiple File Processing Capabilities

🎯 Summary

Introduce comprehensive multiple file processing capabilities that transform the CLI tool from single-file operation to sophisticated batch processing whilst maintaining complete backwards compatibility. This release delivers significant functionality enhancement enabling developers to validate entire codebases efficiently through simultaneous checking of multiple files and directories in a single command.

Transform the validation workflow by expanding CLI argument processing from individual file handling to comprehensive multi-path batch operations. Enhance developer productivity by enabling efficient validation of complex project structures whilst providing enhanced error reporting, improved path validation, and modernised CI/CD integration. Establish robust foundation for enterprise-scale docstring validation workflows.

Key Enhancement Areas:

• Multi-Path CLI Processing: Comprehensive argument transformation supporting multiple file and directory targets
• Enhanced Path Validation: Advanced error reporting with detailed feedback for invalid paths
• Backwards Compatibility Guarantee: Complete preservation of existing single-file functionality and behaviour
• Comprehensive Test Coverage: Seven new testing scenarios covering multiple file operations across all CLI features
• Workflow Modernisation: Removal of deprecated UV installation flags for improved CI reliability

📈 Release Statistics

🔢 Code Changes Summary

• Files Modified: 4 core files with targeted enhancements
• Lines Added: 1,575+ new lines including comprehensive tests and documentation
• Test Enhancement: 354+ new test lines with 7 dedicated multiple file scenarios
• CLI Functionality: 65+ lines of enhanced CLI logic for multi-path processing
• Documentation Updates: 1,215+ lines of changelog and usage examples

📊 Testing Excellence

• New Test Methods: 7 comprehensive multiple file testing scenarios
• Test Coverage: Maintained 100% code coverage across all enhanced functionality
• CLI Integration: Complete integration testing using authentic command-line simulation
• Edge Case Coverage: Comprehensive validation of mixed valid/invalid paths and error conditions

🚀 Multiple File Processing Implementation

🏗️ Core CLI Architecture Enhancement

Transform the CLI argument structure to support comprehensive multiple file and directory targets:

• Parameter Transformation: Enhance CLI argument from single path: Optional[str] to multiple paths: Optional[list[str]] enabling sophisticated batch processing
• Function Signature Evolution: Modify check_docstrings() function to accept paths: list[str] parameter supporting concurrent validation operations
• Advanced Path Validation: Implement comprehensive validation logic identifying and reporting all invalid paths simultaneously rather than failing on first error
• Result Aggregation System: Collect and merge docstring validation results from multiple sources into unified, structured output

Enhanced CLI Signature:

# CLI parameter transformation for multiple file support
def main(
    ctx: Context,
    paths: Optional[list[str]] = Argument(
        None, 
        help="Path(s) to Python file(s) or directory(s) for DFC to check"
    ),
    # ... other parameters preserved
): ...

Function Processing Enhancement:

# Multi-path processing with comprehensive validation
def check_docstrings(
    paths: list[str],  # Enhanced from single path parameter
    config: Optional[str] = None,
    exclude: Optional[list[str]] = None,
    # ... other parameters
): ...

🔍 Advanced Path Validation and Error Management

Implement sophisticated validation logic supporting comprehensive multiple target path analysis:

• Batch Validation Processing: Validate all provided paths simultaneously before processing execution begins
• Structured Error Reporting: Report all invalid paths in single, comprehensively formatted error message with enhanced readability
• Early Validation Strategy: Prevent unnecessary processing overhead by validating complete path set upfront
• Rich Text Error Output: Format invalid path errors with structured bullet points and enhanced terminal formatting

Enhanced Path Validation Logic:

# Comprehensive multi-path validation with detailed error reporting
path_objs: list[Path] = [Path(path) for path in paths]
target_paths: list[Path] = [p for p in path_objs if p.exists()]
invalid_paths: list[Path] = [p for p in path_objs if not p.exists()]

if len(invalid_paths) > 0:
    console.print(
        _red(f"[bold]Error: Paths do not exist:[/bold]"),
        NEW_LINE,
        NEW_LINE.join([f"- '{invalid_path}'" for invalid_path in invalid_paths]),
    )
    raise Exit(1)

🔄 Result Aggregation and Processing Architecture

Implement comprehensive result collection system supporting diverse source integration:

• Iterative Path Processing: Process each valid path individually whilst maintaining complete error isolation between sources
• Advanced Result Merging: Aggregate docstring validation errors from all sources into unified result dictionary structure
• Mixed Path Type Support: Handle sophisticated combinations of individual files and directories seamlessly within single command execution
• Configuration Discovery Enhancement: Utilise first valid path for automatic configuration file discovery when no explicit configuration provided

Multi-Path Processing Logic:

# Enhanced processing supporting multiple paths with result aggregation  
all_results: dict[str, list[DocstringError]] = {}

for target_path in target_paths:
    if target_path.is_file():
        errors: list[DocstringError] = checker.check_file(target_path)
        if errors:
            all_results[str(target_path)] = errors
    else:
        directory_results: dict[str, list[DocstringError]] = checker.check_directory(
            target_path, exclude_patterns=exclude
        )
        all_results.update(directory_results)

💡 Enhanced Usage Examples and CLI Integration

🛠️ Comprehensive Usage Pattern Enhancement

Expand CLI help documentation to demonstrate sophisticated multi-path capabilities:

• Multiple File Examples: Add comprehensive examples demonstrating simultaneous checking of multiple Python files
• Advanced Exclusion Integration: Showcase combining multiple path targets with exclusion patterns for sophisticated filtering operations
• Mixed Usage Scenarios: Provide examples demonstrating concurrent checking of individual files and complete directories within single command execution

New Usage Examples:

# Enhanced multi-file processing capabilities
dfc myfile.py other_file.py                    # Check multiple Python files simultaneously
dfc -x src/app/__init__.py src/                 # Check directory excluding specific file  
dfc file1.py file2.py src/ tests/               # Mixed files and directories
dfc --output=table myfile.py src/ tests/       # Multiple paths with table output
dfc --check src/models/ src/views/              # Batch processing with check flag

🔧 Backwards Compatibility Preservation

Maintain comprehensive backwards compatibility whilst delivering enhanced functionality:

• Single File Operation: Existing dfc myfile.py commands execute identically to previous behaviour patterns
• Directory Processing Continuity: Directory scanning behaviour remains completely unchanged for single directory operations
• Flag Compatibility Assurance: All existing CLI flags (--quiet, --check, --output, etc.) function seamlessly with enhanced multiple path processing
• Consistent Error Handling: Maintain identical error behaviour patterns whether processing single or multiple path targets

🧪 Comprehensive Testing Enhancement

📊 Seven New Testing Scenarios

Implement comprehensive test coverage expansion supporting multiple file functionality validation:

• test_51_multiple_files_success(): Validate successful processing of multiple valid files with appropriate success messaging output
• test_52_multiple_files_with_errors(): Test sophisticated error aggregation when subset of files contain docstring validation issues
• test_53_multiple_files_with_check_flag(): Verify --check flag behaviour with multiple files and appropriate exit code handling
• test_54_multiple_files_nonexistent_path(): Test comprehensive error handling when subset of paths don't exist alongside valid path targets
• test_55_multiple_files_mixed_types(): Validate processing sophisticated combinations of individual files and complete directories
• test_56_multiple_files_table_output(): Test table output formatting with aggregated results from multiple diverse sources
• test_57_multiple_files_quiet_mode(): Verify quiet mode operational behaviour with comprehensive multiple file processing operations

🔍 Testing Architecture Enhancement

Achieve comprehensive coverage expansion supporting robust multiple file functionality validation:

• 354+ New Test Lines: Extensive test coverage addition ensuring robust multiple file functionality across diverse scenarios
• Edge Case Coverage: Test scenarios encompass mixed valid/invalid paths, different output formatting options, and comprehensive error condition handling
• CLI Integration Testing: Complete integration testing utilising typer.testing.CliRunner for authentic CLI behaviour simulation across all scenarios
• Temporary File Management: Robust temporary file creation and cleanup protocols in test scenarios using appropriate context management patterns...

v1.1.0 - Enhance CLI Experience with ASCII Art

🎯 Summary

Introduce the definitive major release of docstring-format-checker, marking the complete evolution from initial concept to production-ready, enterprise-grade Python CLI tool. This comprehensive release represents the culmination of intensive development spanning 189 commits, 14 merged pull requests, and 13 iterative releases, delivering the most sophisticated Python docstring validation solution available today.

Transform from basic validation concept to industry-leading tool with advanced ASCII art CLI experience, comprehensive configuration management, robust cross-platform compatibility, and modern Python ecosystem integration. Establish docstring-format-checker as the authoritative solution for Python documentation quality assurance, combining powerful validation capabilities with exceptional user experience and professional-grade tooling.

Complete Feature Set:

• Dynamic ASCII Art CLI: Intelligent terminal width adaptation with professional pyfiglet banners
• Advanced AST Parsing: Robust code analysis without regex fragility across all Python constructs
• Sophisticated Configuration: Four distinct section types with hierarchical TOML-based discovery
• Rich Terminal Experience: Beautiful coloured output with structured error tables and panels
• Modern Python Integration: Contemporary version management with importlib.metadata and UV packaging
• Comprehensive Testing: 166 tests achieving 100% code coverage across Windows, macOS, and Linux
• Professional Documentation: Complete user guides, API documentation, and configuration examples

🚀 Complete Architecture Overview

🏗️ Core Validation Engine Evolution

Establish the most sophisticated docstring validation system available in the Python ecosystem:

• DocstringChecker(): Advanced validation engine with comprehensive rule enforcement and error reporting
• FunctionAndClassDetails(): Structured representation of code elements for precise analysis and validation
• Enhanced AST Integration: Robust parsing supporting functions, methods, classes, async functions, and @overload decorators
• Multi-Format Support: Intelligent handling of diverse Python code patterns with consistent validation behaviour
• Advanced Error Detection: Sophisticated validation logic for admonitions, section ordering, parameter matching, and content structure

Complete Validation Rule System:

VALID_TYPES = (
    "free_text",          # Summary, details, examples, notes with admonition support
    "list_name",          # Simple name sections with basic validation  
    "list_type",          # Type-only sections (raises, yields) with parentheses checking
    "list_name_and_type", # Parameter-style sections with comprehensive validation
)

⚙️ Advanced Configuration Management

Implement the most flexible configuration system in Python documentation tooling:

• Config(): Comprehensive configuration container with global settings and section definitions
• SectionConfig(): Individual section configuration with validation rules, admonition support, and customisation options
• GlobalConfig(): Global validation behaviour control with allow_undefined_sections, require_docstrings, and check_private flags
• Hierarchical Discovery: Intelligent search for pyproject.toml configuration files up directory trees
• Validation Enforcement: Strict configuration validation with comprehensive error reporting and helpful suggestions

Advanced Configuration Architecture:

[tool.dfc]  # or [tool.docstring-format-checker]
allow_undefined_sections = false
require_docstrings = true  
check_private = true

sections = [
    { order = 1, name = "summary",  type = "free_text",          required = true, admonition = "note", prefix = "!!!" },
    { order = 2, name = "details",  type = "free_text",          required = false, admonition = "abstract", prefix = "???+" },
    { order = 3, name = "params",   type = "list_name_and_type", required = false },
    { order = 4, name = "raises",   type = "list_type",          required = false },
    { order = 5, name = "returns",  type = "list_name_and_type", required = false },
    { order = 6, name = "yields",   type = "list_type",          required = false },
    { order = 7, name = "examples", type = "free_text",          required = false, admonition = "example", prefix = "???+" },
    { order = 8, name = "notes",    type = "free_text",          required = false, admonition = "note", prefix = "???" },
]

🎨 Revolutionary CLI Experience

Deliver the most advanced CLI experience in Python development tooling:

• Dynamic ASCII Art Integration: Professional pyfiglet banner generation with intelligent terminal width adaptation (130-column threshold)
• Rich Terminal Output: Sophisticated coloured output using Rich library with structured error tables, panels, and professional formatting
• Dual Entry Points: Both docstring-format-checker and dfc commands with identical functionality for flexibility
• Comprehensive Help System: Integrated help display combining ASCII banners, standard help, usage examples, and configuration guidance
• Advanced Output Modes: Multiple output formats (table, list) with quiet modes and structured exit codes for diverse workflow integration

Complete CLI Capabilities:

# Multiple invocation methods with rich features
dfc check src/                          # Check directory with ASCII art help
docstring-format-checker check file.py  # Full command name
dfc check --output table --quiet src/   # Customised output formats  
dfc config-example                      # Generate comprehensive configuration
dfc --help                              # Dynamic ASCII art with complete guidance

🎭 Visual Experience Transformation

🖥️ Dynamic ASCII Art System

Revolutionise CLI aesthetics with intelligent ASCII art adaptation:

• Terminal Width Intelligence: Dynamic selection between compact dfc (< 130 columns) and full docstring-format-checker (≥ 130 columns) banners
• Professional Typography: Industry-standard pyfiglet integration with consistent magenta styling and proper markup handling
• Cross-Platform Compatibility: Robust terminal size detection with fallback mechanisms for test environments and CI systems
• Integrated Help Experience: Seamless combination of ASCII banners with Rich-formatted help panels and examples

ASCII Art Display Examples:

Narrow Terminal (< 130 columns):

     _  __      
  __| |/ _| ___ 
 / _` | |_ / __|
| (_| |  _| (__ 
 \__,_|_|  \___|

Wide Terminal (≥ 130 columns):

     _                _        _                    __                            _             _               _             
  __| | ___   ___ ___| |_ _ __(_)_ __   __ _       / _| ___  _ __ _ __ ___   __ _| |_       ___| |__   ___  ___| | _____ _ __ 
 / _` |/ _ \ / __/ __| __| '__| | '_ \ / _` |_____| |_ / _ \| '__| '_ ` _ \ / _` | __|____ / __| '_ \ / _ \/ __| |/ / _ \ '__|
| (_| | (_) | (__\__ \ |_| |  | | | | | (_| |_____|  _| (_) | |  | | | | | | (_| | ||_____| (__| | | |  __/ (__|   <  __/ |   
 \__,_|\___/ \___|___/\__|_|  |_|_| |_|\__, |     |_|  \___/|_|  |_| |_| |_|\__,_|\__|     \___|_| |_|\___|\___|_|\_\___|_|   
                                       |___/                                                                                  

📚 Enhanced User Interface Elements

Deliver comprehensive interface improvements across all user touchpoints:

• Rich Panel Integration: Professional bordered sections for arguments, options, examples, and configuration with consistent styling
• Colour-Coded Examples: Enhanced usage examples with syntax highlighting and descriptive comments for improved comprehension
• Configuration Modernisation: Streamlined configuration examples with inline array syntax replacing nested TOML tables
• Error Message Enhancement: Structured error reporting with file paths, line numbers, function names, and detailed descriptions

🐍 Modern Python Ecosystem Integration

📦 Contemporary Packaging Standards

Embrace modern Python packaging practices with industry-leading approaches:

• Dynamic Version Management: Complete migration from hardcoded versions to importlib.metadata runtime detection
• UV Integration: Native UV package manager support with modern dependency resolution and version management
• Semantic Versioning Alignment: Standardised version format without legacy prefixes (1.1.0 vs v1.1.0)
• Python Version Strategy: Focused support for actively maintained Python versions (3.9-3.13) with dropped legacy support
• Build System Modernisation: Latest uv_build integration with contemporary packaging workflows

Enhanced Package Metadata:

# src/docstring_format_checker/__init__.py - Modern approach
from importlib.metadata import metadata

_metadata = metadata("docstring-format-checker")
__name__: str = _metadata["Name"]
__version__: str = _metadata["Version"]  
__author__: str = _metadata["Author"]
__email__: str = _metadata.get("Email", "")

🏗️ Infrastructure Modernisation

Implement contemporary development infrastructure with professional-grade tooling:

• GitHub Actions Integration: Latest actions/setup-python@v5 with official UV setup actions for enhanced reliability
• Dependency Strategy: Modern dependency management with pyfiglet>=1.0.1 for ASCII art, updated development tools
• Documentation Hosting: Dedicated website integration at data-science-extensions.com replacing README-based documentation
• CI/CD Excellence: Comprehensive testing matrix across platforms with automated coverage rep...