[CHORE]: Script to add relative file path header to each file and verify top level docstring

[crivetimihai]

🔧 Chore Summary

Create a script that automatically checks and optionally adds or fixes relative file path headers in source files. Each Python file should contain a standardized header with its relative path location for improved navigation and documentation consistency.

---

🧱 Area Affected

Choose the general area(s) that this chore affects:

• Pre-commit hooks / linters
• Formatting (black, isort, ruff, etc.)
• Build system or Makefile
• Docs or spellcheck

---

⚙️ Context / Rationale

Currently, source files lack consistent location headers, making it difficult to:

• Navigate large codebases efficiently
• Understand file organization when viewing individual files
• Maintain documentation consistency across the project
• Quickly identify file locations during code reviews

This script will standardize headers across all Python files with the format:

# -*- coding: utf-8 -*-
"""Module Description.
Location: ./relative/path/to/file.py

Copyright 2025
SPDX-License-Identifier: Apache-2.0
Authors: Mihai Criveti

Module documentation...
"""

This reduces tech debt and improves developer experience by providing consistent file location context.

---

📦 Related Make Targets

Reference any relevant Makefile targets that are involved, if applicable:

• make lint - run ruff, mypy, flake8, etc. (should pass after header updates)
• make pre-commit - run pre-configured hooks (may need to handle new headers)
• make check-headers - new target to validate file headers using .github/tools/fix_file_headers.py --check
• make fix-headers - new target to automatically fix missing/incorrect headers using .github/tools/fix_file_headers.py --fix-all

---

📋 Acceptance Criteria

Define what "done" looks like for this task.

Script Requirements:

• Script implemented at .github/tools/fix_file_headers.py
• Script can scan all Python files in the project
• Script can detect missing or incorrect relative path headers
• Script provides interactive mode to review and approve changes
• Script provides batch mode for automated fixes
• Script preserves existing docstring content while updating location
• Script handles edge cases (files without docstrings, existing headers, etc.)

Implementation Requirements:

• Script follows the standardized header format shown in example
• All Python files have correct relative path headers after running
• Headers maintain consistent formatting and structure
• Copyright and license information is preserved/added consistently

Quality Checks:

• Linter runs cleanly (make lint)
• CI passes with no regressions
• No existing functionality is broken
• Script can be integrated into pre-commit hooks (optional)

Documentation:

• Script usage is documented with examples
• Makefile targets are added for header management
• Header format is documented for future reference

---

🧩 Additional Notes

Technical Implementation Notes:

• Script should be placed in .github/tools/fix_file_headers.py
• Use Python's ast module to safely parse and modify Python files
• Preserve original file encodings and line endings
• Handle files that already have partial headers gracefully
• Consider using pathlib for cross-platform path handling

File Selection Criteria:

• Target .py files in project directories
• Exclude virtual environments, build directories, and .git
• Focus on source code files (mcpgateway/, tests/, etc.)

Header Template Variables:

• Location: Relative path from project root (e.g., ./mcpgateway/services/gateway_service.py)
• Copyright: Current year (2025)
• Authors: Configurable, default to "Mihai Criveti"
• License: Apache-2.0 (consistent with project)

Integration Considerations:

• Script should be idempotent (safe to run multiple times)
• Consider adding to pre-commit hooks for new files
• May need to update existing CI/CD checks that parse file headers
• Ensure script works with different Python file structures (modules, packages, scripts)

Example Command Usage:

# Check which files need header updates (dry-run)
python .github/tools/fix_file_headers.py --check

# Interactively review and apply changes
python .github/tools/fix_file_headers.py --interactive

# Automatically fix all files (batch mode)
python .github/tools/fix_file_headers.py --fix-all

# Fix specific directory
python .github/tools/fix_file_headers.py --fix --path mcpgateway/services/