Merge pull request steam-bell-92#1694 from jyotish6699/feature/project-registry-validation-framework

feat: add registry validation framework for project registry

Author: steam-bell-92

CONTRIBUTING.md

@@ -47,10 +47,16 @@ git checkout -b fix/bug-description
 
 ### 3. Make Your Changes
 
-- Write your code following our [Project Guidelines](#-project-guidelines)
+- Write your code following our Project Guidelines
+- Validate `projects_registry.json` before submitting your changes
 - Test your project thoroughly
 - Ensure it follows the repository style
 
+Run the registry validator:
+
+```bash
+python utils/registry_validator.py --strict
+
 ### 4. Commit Your Changes
 
 ```bash
@@ -466,6 +472,44 @@ To run a syntax check across all files (similar to our CI):
 find . -name "*.py" -exec python -m py_compile {} +
 ```
 
+## 📋 Registry Validation
+
+If your contribution adds or modifies `projects_registry.json`, validate the registry before opening a pull request.
+
+### Run validation
+
+```bash
+python utils/registry_validator.py
+```
+
+### Validate a custom registry
+
+```bash
+python utils/registry_validator.py --file projects_registry.json
+```
+
+### JSON output
+
+```bash
+python utils/registry_validator.py --json
+```
+
+### Strict mode
+
+```bash
+python utils/registry_validator.py --strict
+```
+
+The validator checks:
+
+- Valid JSON format
+- Required project fields
+- Valid categories
+- Valid difficulty levels
+- Duplicate project names
+- Duplicate project paths
+- Missing project files
+
 ---
 
 ## 🤔 Questions?

README.md

@@ -240,6 +240,46 @@ pytest tests/test_smoke.py -v
 - Add unit tests for your code
 - Test your project before submitting a PR
 
+### Registry Validator
+
+Before opening a pull request, validate the project registry to ensure all project metadata is correct.
+
+#### Run validation
+
+```bash
+python utils/registry_validator.py
+```
+
+#### Validate a custom registry
+
+```bash
+python utils/registry_validator.py --file projects_registry.json
+```
+
+#### JSON output
+
+```bash
+python utils/registry_validator.py --json
+```
+
+#### Strict mode (CI-friendly)
+
+Returns a non-zero exit code if validation fails.
+
+```bash
+python utils/registry_validator.py --strict
+```
+
+The validator checks:
+
+- Valid JSON format
+- Required project fields
+- Valid categories
+- Valid difficulty levels
+- Duplicate project names
+- Duplicate project paths
+- Missing project files
+
 #### Virtual Environment Reminder
 
 Always activate your virtual environment before working:

projects_registry.json

@@ -785,6 +785,8 @@
       "mines"
     ],
     "path": "games/Minesweeper/minesweeper.py"
+  },
+  {
     "name": "Snake Game",
     "emoji": "🐍",
     "category": "games",

tests/test_registry_validator.py

@@ -0,0 +1,202 @@
+import json
+from pathlib import Path
+
+from utils.registry_validator import RegistryValidator
+
+def write_registry(tmp_path, data):
+    registry = tmp_path / "projects_registry.json"
+
+    registry.write_text(
+        json.dumps(data, indent=2),
+        encoding="utf-8",
+    )
+
+    return registry
+
+def test_valid_registry(tmp_path):
+    project_file = tmp_path / "demo.py"
+    project_file.write_text("print('hello')")
+
+    registry = write_registry(
+        tmp_path,
+        [
+            {
+                "name": "Demo",
+                "emoji": "🔥",
+                "category": "utilities",
+                "difficulty": "beginner",
+                "description": "Demo project",
+                "keywords": ["demo"],
+                "path": "demo.py",
+            }
+        ],
+    )
+
+    validator = RegistryValidator(registry)
+
+    validator.validate()
+
+    assert validator.errors == []
+
+def test_invalid_category(tmp_path):
+    project_file = tmp_path / "demo.py"
+    project_file.write_text("print('hello')")
+
+    registry = write_registry(
+        tmp_path,
+        [
+            {
+                "name": "Demo",
+                "emoji": "🔥",
+                "category": "invalid",
+                "difficulty": "beginner",
+                "description": "Demo",
+                "keywords": ["demo"],
+                "path": "demo.py",
+            }
+        ],
+    )
+
+    validator = RegistryValidator(registry)
+
+    validator.validate()
+
+    assert validator.errors
+
+def test_duplicate_names(tmp_path):
+    (tmp_path / "a.py").write_text("")
+    (tmp_path / "b.py").write_text("")
+
+    registry = write_registry(
+        tmp_path,
+        [
+            {
+                "name": "Demo",
+                "emoji": "🔥",
+                "category": "utilities",
+                "difficulty": "beginner",
+                "description": "One",
+                "keywords": ["demo"],
+                "path": "a.py",
+            },
+            {
+                "name": "Demo",
+                "emoji": "🔥",
+                "category": "utilities",
+                "difficulty": "beginner",
+                "description": "Two",
+                "keywords": ["demo"],
+                "path": "b.py",
+            },
+        ],
+    )
+
+    validator = RegistryValidator(registry)
+
+    validator.validate()
+
+    assert any("Duplicate project name" in e for e in validator.errors)
+
+def test_invalid_difficulty(tmp_path):
+    project_file = tmp_path / "demo.py"
+    project_file.write_text("print('hello')")
+
+    registry = write_registry(
+        tmp_path,
+        [{
+            "name": "Demo",
+            "emoji": "🔥",
+            "category": "utilities",
+            "difficulty": "expert",
+            "description": "Demo",
+            "keywords": ["demo"],
+            "path": "demo.py",
+        }],
+    )
+
+    validator = RegistryValidator(registry)
+    validator.validate()
+
+    assert any("invalid difficulty" in e.lower() for e in validator.errors)
+
+def test_duplicate_paths(tmp_path):
+    (tmp_path / "demo.py").write_text("print('hello')")
+
+    registry = write_registry(
+        tmp_path,
+        [
+            {
+                "name": "Demo1",
+                "emoji": "🔥",
+                "category": "utilities",
+                "difficulty": "beginner",
+                "description": "Demo",
+                "keywords": ["demo"],
+                "path": "demo.py",
+            },
+            {
+                "name": "Demo2",
+                "emoji": "🔥",
+                "category": "utilities",
+                "difficulty": "beginner",
+                "description": "Demo",
+                "keywords": ["demo"],
+                "path": "demo.py",
+            },
+        ],
+    )
+
+    validator = RegistryValidator(registry)
+    validator.validate()
+
+    assert any("duplicate project path" in e.lower() for e in validator.errors)
+
+def test_missing_required_field(tmp_path):
+    (tmp_path / "demo.py").write_text("print('hello')")
+
+    registry = write_registry(
+        tmp_path,
+        [{
+            "name": "Demo",
+            "emoji": "🔥",
+            "category": "utilities",
+            "difficulty": "beginner",
+            "description": "Demo",
+            "path": "demo.py",
+        }],
+    )
+
+    validator = RegistryValidator(registry)
+    validator.validate()
+
+    assert any("missing required fields" in e.lower() for e in validator.errors)
+
+def test_missing_project_file(tmp_path):
+    registry = write_registry(
+        tmp_path,
+        [{
+            "name": "Demo",
+            "emoji": "🔥",
+            "category": "utilities",
+            "difficulty": "beginner",
+            "description": "Demo",
+            "keywords": ["demo"],
+            "path": "missing.py",
+        }],
+    )
+
+    validator = RegistryValidator(registry)
+    validator.validate()
+
+    assert any("missing project file" in e.lower() for e in validator.errors)
+
+def test_invalid_json(tmp_path):
+    registry = tmp_path / "projects_registry.json"
+
+    registry.write_text("{ invalid json", encoding="utf-8")
+
+    validator = RegistryValidator(registry)
+    validator.validate()
+
+    assert any("invalid json" in e.lower() for e in validator.errors)
+