learningcircuit--local-deep-research/.pre-commit-hooks/recommend-docs.py

#!/usr/bin/env python3
"""Gentle reminder to update docs when source files change.

Always exits 0 (non-blocking). Prints a suggestion when source files
are staged without any documentation updates.
"""

import sys
from pathlib import Path

# Allow importing sibling module
sys.path.insert(0, str(Path(__file__).resolve().parent))

from _commit_analysis import analyze_commit


def main():
    analysis = analyze_commit()

    # Silent exit: no source files staged
    if not analysis.source_files:
        return 0

    # Silent exit: docs already included
    if analysis.has_docs:
        return 0

    # Silent exit: trivial change (less than 10 added lines)
    if analysis.total_source_added < 10:
        return 0

    # Print gentle reminder
    print()
    print("  \033[36mDocumentation Reminder\033[0m")
    print("  " + "-" * 40)
    print(
        f"  You're changing {len(analysis.source_files)} source file(s) "
        f"with {analysis.total_source_added} new lines"
    )
    print("  but no documentation (.md) files are staged.")
    print()
    print("  Changed source files:")
    for f in analysis.source_files:
        print(f"    - {f.path} (+{f.added})")
    print()
    print("  Consider updating README.md or docs/ if this changes")
    print("  public behavior, configuration, or APIs.")
    print()

    return 0


if __name__ == "__main__":
    sys.exit(main())