Added patches for P001 and W004 addressing issues #78 #81

Author: Anas-Elhounsri

README.md

@@ -118,9 +118,36 @@ The `repositories.json` file should be structured as follows:
 poetry run rsmetacheck --input repositories.json \
   --somef-output ./results/somef \
   --pitfalls-output ./results/pitfalls \
-  --analysis-output ./results/summary.json
+  --analysis-output ./results/summary.json \
+  --notes-output ./results/notes.json
 ```
 
+#### Version Discrepancy Notes
+
+When a metadata version differs from the release version by a small margin (all version components differ by less than 2, e.g., `0.4.3.dev1` vs `0.4.2`), MetaCheck records a **note** rather than a full pitfall. To capture these observations, use the `--notes-output` flag:
+
+```bash
+poetry run rsmetacheck --input https://github.com/example/repo --notes-output ./notes.json
+```
+
+The notes file is only created when there are observations to report and the `--notes-output` path is specified. Its structure is:
+
+```json
+{
+  "total_notes": 1,
+  "notes": [
+    {
+      "repository": "example/repo",
+      "file_name": "repo_output.json",
+      "code": "P001",
+      "note": "Version discrepancy: metadata '0.4.3.dev1' vs release '0.4.2'"
+    }
+  ]
+}
+```
+
+If the version difference is significant (any component differs by 2 or more, e.g., `0.12.4` vs `0.12.1`), it is still flagged as a pitfall.
+
 #### Skip SoMEF and Analyze Existing Outputs
 
 If you've already run SoMEF separately:

src/rsmetacheck/cli.py

@@ -40,6 +40,11 @@ def cli():
         default=os.path.join(os.getcwd(), "analysis_results.json"),
         help="File path for summary results (default: ./analysis_results.json).",
     )
+    parser.add_argument(
+        "--notes-output",
+        default=None,
+        help="File path for notes output (default: None, notes file is not created unless specified).",
+    )
     parser.add_argument(
         "--threshold",
         type=float,
@@ -89,6 +94,7 @@ def cli():
             args.pitfalls_output,
             args.analysis_output,
             verbose=args.verbose,
+            notes_output=args.notes_output,
         )
 
     else:
@@ -134,6 +140,7 @@ def cli():
             args.pitfalls_output,
             args.analysis_output,
             verbose=args.verbose,
+            notes_output=args.notes_output,
         )
 
 

src/rsmetacheck/detect_pitfalls_main.py

@@ -40,7 +40,7 @@
 from rsmetacheck.scripts.warnings.w010 import detect_git_remote_shorthand_pitfall
 
 
-def detect_all_pitfalls(json_files: Iterable[Path], pitfalls_output_dir: Union[str, Path], output_file: Union[str, Path], verbose: bool = False):
+def detect_all_pitfalls(json_files: Iterable[Path], pitfalls_output_dir: Union[str, Path], output_file: Union[str, Path], verbose: bool = False, notes_output: Union[str, Path] = None):
     """
     Detect all software repository pitfalls in SoMEF output files using modular detectors.
     Now also generates individual JSON-LD files for each repository.
@@ -279,6 +279,7 @@ def detect_all_pitfalls(json_files: Iterable[Path], pitfalls_output_dir: Union[s
     repos_with_target_languages = 0
     jsonld_files_created = 0
     pitfall_counts = [0] * 29
+    notes_list = []
 
     pitfall_detectors = [
         (detect_version_mismatch, "P001"),  # Index 0 -> P001
@@ -357,13 +358,28 @@ def detect_all_pitfalls(json_files: Iterable[Path], pitfalls_output_dir: Union[s
                         issue_type = "Pitfall" if pitfall_result.get("has_pitfall", False) else "Warning"
                         print(f"{pitfall_code} - {issue_type} found in {json_file.name}")
 
+                    if pitfall_result.get("has_note", False):
+                        repo_name = json_file.name
+                        if "full_name" in somef_data and somef_data["full_name"]:
+                            for item in somef_data["full_name"]:
+                                if "result" in item and "value" in item["result"]:
+                                    repo_name = item["result"]["value"]
+                                    break
+                        notes_list.append({
+                            "repository": repo_name,
+                            "file_name": json_file.name,
+                            "code": pitfall_code,
+                            "note": pitfall_result.get("note_text", "")
+                        })
+                        print(f"{pitfall_code} - Note added for {json_file.name}")
+
                 except Exception as e:
                     print(f"Error running {pitfall_code} detector on {json_file.name}: {e}")
                     continue
 
             try:
                 has_any_issue = any(
-                    result.get("has_pitfall", False) or result.get("has_warning", False)
+                    result.get("has_pitfall", False) or result.get("has_warning", False) or result.get("has_note", False)
                     for result in repo_pitfall_results
                 )
 
@@ -437,11 +453,28 @@ def detect_all_pitfalls(json_files: Iterable[Path], pitfalls_output_dir: Union[s
 
         print(f"Summary results saved to: {output_file}")
 
+        if notes_list and notes_output:
+            try:
+                notes_path = Path(notes_output)
+                notes_data = {
+                    "total_notes": len(notes_list),
+                    "notes": notes_list
+                }
+                with open(notes_path, 'w', encoding='utf-8') as f:
+                    json.dump(notes_data, f, indent=2, ensure_ascii=False)
+                print(f"\nNotes ({len(notes_list)}) saved to: {notes_path}")
+            except Exception as e:
+                print(f"Error writing notes file: {e}")
+        elif notes_list:
+            print(f"\n{len(notes_list)} note(s) were found but no --notes-output path was provided. Skipping notes file.")
+        else:
+            print("\nNo notes generated.")
+
     except Exception as e:
         print(f"Error writing output file: {e}")
 
 
-def main(input_dir=None, somef_json_paths=None, pitfalls_dir=None, analysis_output=None, verbose=False):
+def main(input_dir=None, somef_json_paths=None, pitfalls_dir=None, analysis_output=None, verbose=False, notes_output=None):
     """
     Main function to run all pitfall detections.
 
@@ -451,6 +484,7 @@ def main(input_dir=None, somef_json_paths=None, pitfalls_dir=None, analysis_outp
         pitfalls_dir (str|Path, optional): Directory to save pitfall JSON-LD files.
         analysis_output (str|Path, optional): Path to save summary results JSON.
         verbose (bool, optional): Include both detected AND undetected pitfalls in JSON-LD.
+        notes_output (str|Path, optional): Path to save notes JSON file.
 
     Note: Provide either input_dir OR somef_json_paths, not both.
           If both are provided, somef_json_paths takes precedence.
@@ -481,7 +515,7 @@ def main(input_dir=None, somef_json_paths=None, pitfalls_dir=None, analysis_outp
         print("No JSON files found for analysis.")
         return
 
-    detect_all_pitfalls(json_files, pitfalls_directory, output_file, verbose)
+    detect_all_pitfalls(json_files, pitfalls_directory, output_file, verbose, notes_output)
 
 if __name__ == "__main__":
     main()

src/rsmetacheck/run_analyzer.py

@@ -3,7 +3,7 @@
 from rsmetacheck.detect_pitfalls_main import main
 
 
-def run_analysis(somef_input: Union[str, Path, Iterable[Path]], pitfalls_dir: Union[str, Path], analysis_file: Union[str, Path], verbose: bool = False):
+def run_analysis(somef_input: Union[str, Path, Iterable[Path]], pitfalls_dir: Union[str, Path], analysis_file: Union[str, Path], verbose: bool = False, notes_output: Union[str, Path] = None):
     """
     Run metadata analysis using existing code.
 
@@ -13,17 +13,18 @@ def run_analysis(somef_input: Union[str, Path, Iterable[Path]], pitfalls_dir: Un
         pitfalls_dir: Directory to save pitfall JSON-LD files
         analysis_file: Path to save summary results JSON
         verbose: bool indicating if both detected and undetected checks should be logged.
+        notes_output: Path to save notes JSON file.
     """
     print(f"\nRunning analysis...")
 
     if isinstance(somef_input, (str, Path)):
         somef_path = Path(somef_input)
         if somef_path.is_dir():
             print(f"Using directory: {somef_input}")
-            main(input_dir=somef_input, pitfalls_dir=pitfalls_dir, analysis_output=analysis_file, verbose=verbose)
+            main(input_dir=somef_input, pitfalls_dir=pitfalls_dir, analysis_output=analysis_file, verbose=verbose, notes_output=notes_output)
         else:
             print(f"Error: {somef_input} is not a valid directory")
     else:
         json_files = list(somef_input)
         print(f"Using {len(json_files)} specified JSON files")
-        main(somef_json_paths=json_files, pitfalls_dir=pitfalls_dir, analysis_output=analysis_file, verbose=verbose)
+        main(somef_json_paths=json_files, pitfalls_dir=pitfalls_dir, analysis_output=analysis_file, verbose=verbose, notes_output=notes_output)

src/rsmetacheck/scripts/pitfalls/p001.py

@@ -1,7 +1,33 @@
+import re
 from typing import Dict, Optional
 from rsmetacheck.utils.pitfall_utils import normalize_version
 from rsmetacheck.utils.pitfall_utils import extract_metadata_source_filename
 
+
+def _parse_version_components(version_str: str) -> tuple:
+    cleaned = re.sub(r"[-_.]?(dev|alpha|beta|rc|pre|post|a|b)\d*.*", "", version_str, flags=re.IGNORECASE)
+    parts = re.findall(r"\d+", cleaned)
+    components = [int(p) for p in parts[:3]]
+    while len(components) < 3:
+        components.append(0)
+    return tuple(components)
+
+
+def _version_diff_significant(v1: str, v2: str) -> bool:
+    c1 = _parse_version_components(v1)
+    c2 = _parse_version_components(v2)
+    for a, b in zip(c1, c2):
+        if abs(a - b) >= 2:
+            return True
+    return False
+
+
+def _metadata_ahead_of_release(metadata_version: str, release_version: str) -> bool:
+    mc = _parse_version_components(metadata_version)
+    rc = _parse_version_components(release_version)
+    return mc > rc
+
+
 def extract_version_from_metadata(somef_data: Dict) -> Optional[Dict[str, str]]:
     """
     Extract version from metadata files (codemeta.json, DESCRIPTION, etc.) in SoMEF output.
@@ -69,11 +95,13 @@ def detect_version_mismatch(somef_data: Dict, file_name: str) -> Dict:
     """
     result = {
         "has_pitfall": False,
+        "has_note": False,
         "file_name": file_name,
         "metadata_version": None,
         "release_version": None,
         "metadata_source": None,
-        "metadata_source_file": None
+        "metadata_source_file": None,
+        "note_text": None
     }
 
     metadata_version_info = extract_version_from_metadata(somef_data)
@@ -89,7 +117,11 @@ def detect_version_mismatch(somef_data: Dict, file_name: str) -> Dict:
         result["metadata_source"] = metadata_version_info["source"]
         result["metadata_source_file"] = extract_metadata_source_filename(metadata_version_info["source"])
 
-        if metadata_version != normalized_release_version:
-            result["has_pitfall"] = True
+        if _metadata_ahead_of_release(metadata_version, normalized_release_version):
+            if _version_diff_significant(metadata_version, normalized_release_version):
+                result["has_pitfall"] = True
+            else:
+                result["has_note"] = True
+                result["note_text"] = f"Version discrepancy: metadata '{metadata_version}' vs release '{normalized_release_version}'"
 
     return result

src/rsmetacheck/scripts/warnings/w004.py

@@ -1,5 +1,17 @@
+import re
 from typing import Dict
 
+
+def _name_contains_version(name: str) -> bool:
+    return bool(re.search(r"\d", name))
+
+
+def _value_is_list(result_data: Dict) -> bool:
+    name_val = result_data.get("name")
+    value_val = result_data.get("value")
+    return isinstance(name_val, list) or isinstance(value_val, list)
+
+
 def detect_programming_language_no_version_pitfall(somef_data: Dict, file_name: str) -> Dict:
     """
     Detect when programming languages or requirements in codemeta.json do not have versions
@@ -26,6 +38,13 @@ def detect_programming_language_no_version_pitfall(somef_data: Dict, file_name:
 
                         if "version" not in result_data or result_data.get("version") is None:
                             lang_name = result_data.get("name", "Unknown")
+
+                            if _value_is_list(result_data):
+                                continue
+
+                            if isinstance(lang_name, str) and _name_contains_version(lang_name):
+                                continue
+
                             result["programming_languages_without_version"].append(lang_name)
                             result["source"] = source
                             result["has_warning"] = True

src/rsmetacheck/utils/json_ld_utils.py

@@ -61,7 +61,7 @@ def fetch_latest_commit_id(repo_url: str) -> str:
 
     elif repo_url.startswith("https://"):
         # Handles gitlab.com and any self-hosted GitLab instance.
-        # The GitLab API v4 is tried; a failed request returns 'Unknown' gracefully.
+        # The GitLab API v4 is tried; a failed request returns 'Unknown'
         parsed = urllib.parse.urlparse(repo_url)
         host = f"{parsed.scheme}://{parsed.netloc}"
         project_path = parsed.path.strip("/")