[CHORE] Check SPDX headers Makefile and GitHub Actions target - ensure all files have File, Author(s) and SPDX headers

[crivetimihai]

🔧 Chore Summary

Create validation targets to ensure all Python source files contain proper SPDX license headers, copyright notices, and author information. This builds on the file path header script from task #317 to create comprehensive header validation for license compliance and proper attribution.

---

🧱 Area Affected

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

• GitHub Actions / CI Pipelines
• Pre-commit hooks / linters
• Build system or Makefile
• SBOM, CVE scans, licenses, or security checks

---

⚙️ Context / Rationale

License compliance and proper attribution require consistent license headers across all source files. Currently, the project uses Apache-2.0 license with SPDX identifiers, but not all files may have complete headers.

This task ensures:

• Proper SPDX license identification for automated tools
• Consistent copyright and authorship attribution
• SBOM generation and license scanning accuracy

---

📦 Related Make Targets

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

• make lint - run ruff, mypy, flake8, etc. (should include SPDX validation)
• make check-headers - existing target from [CHORE]: Script to add relative file path header to each file and verify top level docstring #317 (extend to include SPDX checks)
• make check-spdx - new target to specifically validate SPDX/license headers
• make fix-spdx - new target to automatically add missing SPDX headers
• make sbom - generate CycloneDX software bill of materials (benefits from proper headers)
• make pip-licenses - generate markdown license inventory (benefits from proper headers)
• make pre-commit - run pre-configured hooks (should validate headers)

---

📋 Acceptance Criteria

Define what "done" looks like for this task.

Header Validation Requirements:

• All Python files have proper encoding declaration (# -*- coding: utf-8 -*-)
• All Python files have copyright notice (Copyright 2025)
• All Python files have SPDX license identifier (SPDX-License-Identifier: Apache-2.0)
• All Python files have Authors field (Authors: Name1, Name2)
• Script can detect missing or malformed license headers
• Script provides clear reporting of non-compliant files

Implementation Requirements:

• Extend .github/tools/fix_file_headers.py from [CHORE]: Script to add relative file path header to each file and verify top level docstring #317 to include SPDX validation
• Create make check-spdx target for header validation
• Create make fix-spdx target for automatic header repair
• Add GitHub Actions workflow step to validate headers in CI
• Integration with existing pre-commit hooks

Quality & Compliance:

• All source files pass SPDX header validation
• CI pipeline fails on missing/invalid license headers
• SBOM generation includes accurate license information
• License inventory tools work correctly with proper headers
• No regressions in existing linting or formatting

Documentation & Integration:

• Makefile targets documented with proper help text
• GitHub Actions integration documented
• CONTRIBUTING.md updated with header requirements (if applicable)
• Developer guidelines include license header examples

---

🧩 Additional Notes

Required Header Format:
Based on existing project files, the standardized header should be:

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

Copyright 2025
SPDX-License-Identifier: Apache-2.0
Authors: Mihai Criveti, [Additional Authors]

Module documentation...
"""

Technical Implementation:

• Extend the existing .github/tools/fix_file_headers.py script from task [CHORE]: Script to add relative file path header to each file and verify top level docstring #317
• Use regex patterns to validate header components
• Support for multiple authors in comma-separated format
• Validate SPDX license identifier matches project license (Apache-2.0)
• Handle edge cases (test files, generated files, etc.)

File Selection Criteria:

• All .py files in mcpgateway/, tests/, and project root
• Exclude: __pycache__, .venv, build/, dist/, .git/
• Include: source files, test files, scripts, and tools
• Consider: migration files in alembic/versions/ (may have different requirements)

GitHub Actions Integration:

- name: Check SPDX License Headers
  run: |
    python .github/tools/fix_file_headers.py --check-spdx
    if [ $? -ne 0 ]; then
      echo "❌ License header validation failed"
      echo "Run 'make fix-spdx' to automatically fix headers"
      exit 1
    fi

Makefile Integration:

check-spdx:                    ## 📜 Validate SPDX license headers
	@python .github/tools/fix_file_headers.py --check-spdx

fix-spdx:                      ## 📜 Fix missing SPDX license headers  
	@python .github/tools/fix_file_headers.py --fix-spdx

Error Reporting:

• Clear output showing which files are missing headers
• Specific guidance on what header components are missing
• Summary statistics (X/Y files compliant)
• Integration with existing CI/CD failure reporting

Dependencies:

• Depends on task [CHORE]: Script to add relative file path header to each file and verify top level docstring #317 (file path header script)
• Should work with existing make sbom and make pip-licenses targets
• Compatible with current pre-commit hook configuration
• No additional Python dependencies required (use standard library)