feat: add SPDX license identifiers to all Python files (issue #4) (#31)

Implement comprehensive SPDX licensing compliance across the codebase
for improved license clarity and machine-readable attribution.

Changes:
- Add 'SPDX-License-Identifier: MIT' to all 77 Python files
- Create scripts/check-spdx.py for automated SPDX validation
- Integrate SPDX check into local quality checks (run-quality-checks.sh)
- Add SPDX validation to CI/CD pipeline (.github/workflows/ci.yml)
- Update contribution guidelines with SPDX requirements
- Add logging consistency check to CI/CD pipeline

Benefits:
- Aligns with Python packaging standards (PEP 639)
- Enables machine-readable license detection
- Supports automated license compliance checking
- Improves clarity for contributors and package managers

Closes #4

Co-authored-by: florath-ai-assistant[bot] <Andreas.Florath@telekom.de>

Author: coding-ai-assistant[bot]

.github/community/CONTRIBUTING.md

@@ -77,6 +77,35 @@ Then create a Pull Request on GitHub.
 - Maximum line length: 88 characters (Black default)
 - Use descriptive variable names
 - Add docstrings for classes and functions
+- **REQUIRED**: Include SPDX license identifier at the top of every Python file
+
+### SPDX License Requirements
+
+All Python source files must include an SPDX license identifier for licensing clarity and compliance:
+
+**For files without shebang lines:**
+```python
+# SPDX-License-Identifier: MIT
+"""Module docstring here."""
+```
+
+**For script files with shebang:**
+```python
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+"""Script docstring here."""
+```
+
+**Why SPDX identifiers are required:**
+- Provides machine-readable licensing information
+- Aligns with Python packaging standards (PEP 639)
+- Enables automated license compliance checking
+- Improves clarity for contributors and users
+
+The SPDX check runs automatically in CI/CD and can be tested locally:
+```bash
+python scripts/check-spdx.py
+```
 
 ### Commit Messages
 Use conventional commit format:

.github/workflows/ci.yml

@@ -47,6 +47,14 @@ jobs:
       run: |
         mypy src/ --strict
 
+    - name: Check SPDX license identifiers
+      run: |
+        python scripts/check-spdx.py
+
+    - name: Check logging consistency
+      run: |
+        python scripts/check-logging.py
+
   test:
     name: Tests
     runs-on: ubuntu-latest

scripts/bump_version.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
 """
 Version bumping utility for aletheia-probe.
 

scripts/check-logging.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
 """Script to enforce consistent logging practices in the codebase.
 
 This script checks that no files use direct logging.getLogger() and instead

scripts/check-spdx.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+"""Script to verify SPDX license identifiers are present in all Python files."""
+
+import sys
+from pathlib import Path
+
+
+def check_spdx_header(file_path: Path) -> tuple[bool, str]:
+    """Check if a Python file has a valid SPDX license identifier.
+
+    Returns:
+        Tuple of (has_valid_spdx, error_message)
+    """
+    try:
+        with open(file_path, encoding='utf-8') as f:
+            lines = f.readlines()
+    except Exception as e:
+        return False, f"Error reading file: {e}"
+
+    if not lines:
+        return False, "File is empty"
+
+    # Check first few lines for SPDX identifier
+    for line in lines[:10]:  # Check first 10 lines
+        if 'SPDX-License-Identifier:' in line:
+            # Verify it's the correct MIT license
+            if 'MIT' in line:
+                # Check that it's a properly formatted comment
+                stripped = line.strip()
+                if stripped.startswith('#') and 'SPDX-License-Identifier: MIT' in stripped:
+                    return True, ""
+                else:
+                    return False, f"SPDX header found but incorrectly formatted: '{stripped}'"
+            else:
+                return False, f"SPDX header found but wrong license: '{line.strip()}'"
+
+    return False, "No SPDX license identifier found"
+
+
+def main() -> int:
+    """Main function to check SPDX headers in all Python files."""
+    project_root = Path(__file__).parent.parent
+
+    # Find all Python files
+    python_files = list(project_root.glob("**/*.py"))
+
+    # Remove this script itself from the check if it exists
+    script_path = Path(__file__).resolve()
+    python_files = [f for f in python_files if f.resolve() != script_path]
+
+    missing_spdx: list[tuple[Path, str]] = []
+    total_files = len(python_files)
+
+    print(f"Checking SPDX license identifiers in {total_files} Python files...")
+
+    for py_file in python_files:
+        has_spdx, error_msg = check_spdx_header(py_file)
+        if not has_spdx:
+            missing_spdx.append((py_file, error_msg))
+
+    # Report results
+    if missing_spdx:
+        print(f"\n❌ SPDX Check FAILED: {len(missing_spdx)} file(s) missing or have invalid SPDX headers:")
+        for file_path, error in missing_spdx:
+            rel_path = file_path.relative_to(project_root)
+            print(f"  - {rel_path}: {error}")
+
+        print("\nTo fix these issues, add the following line at the top of each file")
+        print("(after any shebang line):")
+        print("  # SPDX-License-Identifier: MIT")
+
+        return 1  # Exit with error code
+    else:
+        print(f"✅ SPDX Check PASSED: All {total_files} Python files have valid SPDX headers")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/run-quality-checks.sh

@@ -52,6 +52,9 @@ run_check "Pytest with coverage" pytest --cov=src --cov-report=term-missing test
 # 5. Logging consistency check
 run_check "Logging consistency" python scripts/check-logging.py || true
 
+# 6. SPDX license identifier check
+run_check "SPDX license identifiers" python scripts/check-spdx.py || true
+
 # Final summary
 echo -e "${BLUE}========================================${NC}"
 if [ $FAILED -eq 0 ]; then

src/aletheia_probe/__init__.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MIT
 """Journal Assessment Tool - Automated predatory journal detection."""
 
 from importlib.metadata import PackageNotFoundError, version

src/aletheia_probe/article_retraction_checker.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MIT
 """Article-level retraction checking using multiple data sources."""
 
 import asyncio

src/aletheia_probe/backends/__init__.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MIT
 """Backend modules for journal assessment."""
 
 # Import backends to register them

src/aletheia_probe/backends/algerian_ministry.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MIT
 """Algerian Ministry backend for predatory journal verification."""
 
 from .base import CachedBackend, get_backend_registry