rsmetacheck 0.2.1__tar.gz

rsmetacheck-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anas El Hounsri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rsmetacheck-0.2.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: rsmetacheck
+Version: 0.2.1
+Summary: Detect metadata pitfalls in software repositories
+License-File: LICENSE
+Author: Anas El Hounsri
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: requests
+Requires-Dist: somef
+Description-Content-Type: text/markdown
+
+[![DOI](https://zenodo.org/badge/1050222589.svg)](https://doi.org/10.5281/zenodo.18313677)
+
+# Research Software MetaCheck (a Pitfall/Warning Detection Tool)
+
+This project provides an automated tool for detecting common metadata quality issues (pitfalls & Warnings)
+in software repositories. The tool analyzes SoMEF (Software Metadata Extraction Framework) output
+files to identify various problems in repository metadata
+files such as `codemeta.json`, `package.json`, `setup.py`, `DESCRIPTION`, and others.
+
+## Overview
+
+MetaCheck identifies **29 different types of metadata quality issues** across multiple programming languages
+(Python, Java, C++, C, R, Rust). These pitfalls range from version mismatches and
+license template placeholders to broken URLs and improperly formatted metadata fields.
+
+### Supported Pitfall Types
+
+The tool detects the following categories of issues:
+
+- **Version-related pitfalls**: Version mismatches between metadata files and releases
+- **License-related pitfalls**: Template placeholders, copyright-only licenses, missing version specifications
+- **URL validation pitfalls**: Broken links for CI, software requirements, download URLs
+- **Metadata format pitfalls**: Improper field formatting, multiple authors in single fields, etc...
+- **Identifier pitfalls**: Invalid or missing unique identifiers, bare DOIs
+- **Repository reference pitfalls**: Mismatched code repositories, Git shorthand usage
+
+## Requirements
+
+- **Python 3.10**
+- Required Python packages:
+  - `requests` (for URL validation)
+  - `pathlib` (built-in)
+  - `json` (built-in)
+  - `re` (built-in)
+  - `somef` (For extracting metadata from the repositories)
+
+## Installation
+
+### Using Poetry (Recommended)
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://github.com/SoftwareUnderstanding/RsMetaCheck.git
+   cd RsMetaCheck
+   ```
+
+2. **Install with Poetry**:
+
+   ```bash
+   poetry install
+   ```
+
+3. **Configure SoMEF** (optional but recommended):
+   Initially, the installation process will run `somef configure -a` to automatically set it up and install the necessary packages but the rate limit will be low. If you need more, you should reconfigure SoMEF, you can run the following command:
+   ```bash
+   poetry run somef configure
+   ```
+   Then add your GitHub authentication token to avoid API rate limits when analyzing repositories in batches.
+
+### Using pip
+
+Alternatively, you can install directly from GitHub:
+
+```bash
+pip install git+https://github.com/SoftwareUnderstanding/RsMetaCheck.git
+```
+
+## Usage
+
+### Run the Detection Tool
+
+#### Analyze a Single Repository
+
+```bash
+poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse
+```
+
+#### Analyze Multiple Repositories from a JSON File
+
+```bash
+poetry run rsmetacheck --input repositories.json
+```
+
+The `repositories.json` file should be structured as follows:
+
+```json
+{
+  "repositories": [
+    "https://gitlab.com/example/example_repo_1",
+    "https://gitlab.com/example/example_repo_2",
+    "https://github.com/example/example_repo_3"
+  ]
+}
+```
+
+#### Customize Output Paths
+
+```bash
+poetry run rsmetacheck --input repositories.json \
+  --somef-output ./results/somef \
+  --pitfalls-output ./results/pitfalls \
+  --analysis-output ./results/summary.json
+```
+
+#### Skip SoMEF and Analyze Existing Outputs
+
+If you've already run SoMEF separately:
+
+```bash
+poetry run rsmetacheck --skip-somef --input somef_outputs/*.json
+```
+
+Or for multiple paths:
+
+```bash
+poetry run rsmetacheck --skip-somef --input my_somef_outputs_1/*.json my_somef_outputs_2/*.json
+```
+
+#### Verbose Output for Passed Checks
+
+By default, the JSON-LD files generated by RsMetaCheck will only contain information about pitfalls and warnings that were actually detected. If you want to include all tests in the final JSON-LD, even tests that the repository successfully passed, use the `--verbose` flag:
+
+```bash
+poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --verbose
+```
+
+### Output
+
+The tool will:
+
+- Process all JSON files in the SoMEF output directory (by default `somef_outputs` created by the tool)
+- Display progress messages showing detected pitfalls
+- Generate JSON-LD files of detailed Pitfalls and Warnings detected by the tool in `output_1_pitfalls.jsonld`,
+  `output_2_pitfalls.jsonld`, etc... in `pitfalls` (by default created by the tool) directory
+- Generate a comprehensive report in `all_pitfalls_results.json`
+
+The output file contains:
+
+- EVERSE standardized JSON-LD output of each repository
+- Summary statistics of analyzed repositories
+- Count and percentage for each pitfall type
+- Language-specific breakdown for repositories with target languages
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"There is no valid repository URL" error**: Ensure the JSON file that contains the repositories
+   has a valid structure and that you are inputing the correct path
+2. **Network timeouts**: Some pitfalls validate URLs and may time out this is normal behavior
+
+### Performance Notes
+
+- URL validation pitfalls may take longer due to network requests
+- Large datasets may require several minutes to complete analysis
+- Progress is displayed in real-time showing which pitfalls are found
+
+## Contributing
+
+The system is designed with modularity in mind. Each pitfall detector is implemented as a
+separate module in the `scripts/` directory, making it easy to add new pitfall types or modify
+existing detection logic.
+

rsmetacheck-0.2.1/README.md

@@ -0,0 +1,163 @@
+[![DOI](https://zenodo.org/badge/1050222589.svg)](https://doi.org/10.5281/zenodo.18313677)
+
+# Research Software MetaCheck (a Pitfall/Warning Detection Tool)
+
+This project provides an automated tool for detecting common metadata quality issues (pitfalls & Warnings)
+in software repositories. The tool analyzes SoMEF (Software Metadata Extraction Framework) output
+files to identify various problems in repository metadata
+files such as `codemeta.json`, `package.json`, `setup.py`, `DESCRIPTION`, and others.
+
+## Overview
+
+MetaCheck identifies **29 different types of metadata quality issues** across multiple programming languages
+(Python, Java, C++, C, R, Rust). These pitfalls range from version mismatches and
+license template placeholders to broken URLs and improperly formatted metadata fields.
+
+### Supported Pitfall Types
+
+The tool detects the following categories of issues:
+
+- **Version-related pitfalls**: Version mismatches between metadata files and releases
+- **License-related pitfalls**: Template placeholders, copyright-only licenses, missing version specifications
+- **URL validation pitfalls**: Broken links for CI, software requirements, download URLs
+- **Metadata format pitfalls**: Improper field formatting, multiple authors in single fields, etc...
+- **Identifier pitfalls**: Invalid or missing unique identifiers, bare DOIs
+- **Repository reference pitfalls**: Mismatched code repositories, Git shorthand usage
+
+## Requirements
+
+- **Python 3.10**
+- Required Python packages:
+  - `requests` (for URL validation)
+  - `pathlib` (built-in)
+  - `json` (built-in)
+  - `re` (built-in)
+  - `somef` (For extracting metadata from the repositories)
+
+## Installation
+
+### Using Poetry (Recommended)
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://github.com/SoftwareUnderstanding/RsMetaCheck.git
+   cd RsMetaCheck
+   ```
+
+2. **Install with Poetry**:
+
+   ```bash
+   poetry install
+   ```
+
+3. **Configure SoMEF** (optional but recommended):
+   Initially, the installation process will run `somef configure -a` to automatically set it up and install the necessary packages but the rate limit will be low. If you need more, you should reconfigure SoMEF, you can run the following command:
+   ```bash
+   poetry run somef configure
+   ```
+   Then add your GitHub authentication token to avoid API rate limits when analyzing repositories in batches.
+
+### Using pip
+
+Alternatively, you can install directly from GitHub:
+
+```bash
+pip install git+https://github.com/SoftwareUnderstanding/RsMetaCheck.git
+```
+
+## Usage
+
+### Run the Detection Tool
+
+#### Analyze a Single Repository
+
+```bash
+poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse
+```
+
+#### Analyze Multiple Repositories from a JSON File
+
+```bash
+poetry run rsmetacheck --input repositories.json
+```
+
+The `repositories.json` file should be structured as follows:
+
+```json
+{
+  "repositories": [
+    "https://gitlab.com/example/example_repo_1",
+    "https://gitlab.com/example/example_repo_2",
+    "https://github.com/example/example_repo_3"
+  ]
+}
+```
+
+#### Customize Output Paths
+
+```bash
+poetry run rsmetacheck --input repositories.json \
+  --somef-output ./results/somef \
+  --pitfalls-output ./results/pitfalls \
+  --analysis-output ./results/summary.json
+```
+
+#### Skip SoMEF and Analyze Existing Outputs
+
+If you've already run SoMEF separately:
+
+```bash
+poetry run rsmetacheck --skip-somef --input somef_outputs/*.json
+```
+
+Or for multiple paths:
+
+```bash
+poetry run rsmetacheck --skip-somef --input my_somef_outputs_1/*.json my_somef_outputs_2/*.json
+```
+
+#### Verbose Output for Passed Checks
+
+By default, the JSON-LD files generated by RsMetaCheck will only contain information about pitfalls and warnings that were actually detected. If you want to include all tests in the final JSON-LD, even tests that the repository successfully passed, use the `--verbose` flag:
+
+```bash
+poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --verbose
+```
+
+### Output
+
+The tool will:
+
+- Process all JSON files in the SoMEF output directory (by default `somef_outputs` created by the tool)
+- Display progress messages showing detected pitfalls
+- Generate JSON-LD files of detailed Pitfalls and Warnings detected by the tool in `output_1_pitfalls.jsonld`,
+  `output_2_pitfalls.jsonld`, etc... in `pitfalls` (by default created by the tool) directory
+- Generate a comprehensive report in `all_pitfalls_results.json`
+
+The output file contains:
+
+- EVERSE standardized JSON-LD output of each repository
+- Summary statistics of analyzed repositories
+- Count and percentage for each pitfall type
+- Language-specific breakdown for repositories with target languages
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"There is no valid repository URL" error**: Ensure the JSON file that contains the repositories
+   has a valid structure and that you are inputing the correct path
+2. **Network timeouts**: Some pitfalls validate URLs and may time out this is normal behavior
+
+### Performance Notes
+
+- URL validation pitfalls may take longer due to network requests
+- Large datasets may require several minutes to complete analysis
+- Progress is displayed in real-time showing which pitfalls are found
+
+## Contributing
+
+The system is designed with modularity in mind. Each pitfall detector is implemented as a
+separate module in the `scripts/` directory, making it easy to add new pitfall types or modify
+existing detection logic.

rsmetacheck-0.2.1/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "rsmetacheck"
+version = "0.2.1"
+description = "Detect metadata pitfalls in software repositories"
+authors = ["Anas El Hounsri"]
+readme = "README.md"
+packages = [{include = "metacheck", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+requests = "*"
+somef = "*"
+
+[tool.poetry.scripts]
+rsmetacheck = "metacheck.cli:cli"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

rsmetacheck-0.2.1/src/metacheck/__init__.py

@@ -0,0 +1,2 @@
+from .detect_pitfalls_main import main
+from .cli import cli

rsmetacheck-0.2.1/src/metacheck/cli.py

@@ -0,0 +1,91 @@
+import argparse
+import os
+from pathlib import Path
+from metacheck.run_somef import run_somef_batch, run_somef_single, ensure_somef_configured
+from metacheck.run_analyzer import run_analysis
+
+
+def cli():
+    parser = argparse.ArgumentParser(description="Detect metadata pitfalls in software repositories using SoMEF.")
+    parser.add_argument(
+        "--input",
+        nargs="+",
+        required=True,
+        help="One or more: GitHub/GitLab URLs, JSON files containing repositories, OR existing SoMEF output files when using --skip-somef."
+    )
+    parser.add_argument(
+        "--skip-somef",
+        action="store_true",
+        help="Skip SoMEF execution and analyze existing SoMEF output files directly. --input should point to SoMEF JSON files."
+    )
+    parser.add_argument(
+        "--pitfalls-output",
+        default=os.path.join(os.getcwd(), "pitfalls_outputs"),
+        help="Directory to store pitfall JSON-LD files (default: ./pitfalls_outputs)."
+    )
+    parser.add_argument(
+        "--somef-output",
+        default=os.path.join(os.getcwd(), "somef_outputs"),
+        help="Directory to store SoMEF output files (default: ./somef_outputs)."
+    )
+    parser.add_argument(
+        "--analysis-output",
+        default=os.path.join(os.getcwd(), "analysis_results.json"),
+        help="File path for summary results (default: ./analysis_results.json)."
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.8,
+        help="SoMEF confidence threshold (default: 0.8). Only used when running SoMEF."
+    )
+
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Include both detected AND undetected pitfalls in the output JSON-LD."
+    )
+
+    args = parser.parse_args()
+
+    if args.skip_somef:
+        print(f"Skipping SoMEF execution. Analyzing {len(args.input)} existing SoMEF output files...")
+
+        somef_json_paths = []
+        for json_path in args.input:
+            if not os.path.exists(json_path):
+                print(f"Warning: File not found, skipping: {json_path}")
+                continue
+            somef_json_paths.append(Path(json_path))
+
+        if not somef_json_paths:
+            print("Error: No valid SoMEF output files found.")
+            return
+
+        print(f"Analyzing {len(somef_json_paths)} SoMEF output files...")
+        run_analysis(somef_json_paths, args.pitfalls_output, args.analysis_output, verbose=args.verbose)
+
+    else:
+        ensure_somef_configured()
+
+        threshold = args.threshold
+        somef_output_dir = args.somef_output
+
+        print(f"Detected {len(args.input)} input(s):")
+
+        for input_item in args.input:
+            if input_item.startswith("http://") or input_item.startswith("https://"):
+                print(f"Processing repository URL: {input_item}")
+                run_somef_single(input_item, somef_output_dir, threshold)
+            elif os.path.exists(input_item):
+                print(f"Processing repositories from file: {input_item}")
+                run_somef_batch(input_item, somef_output_dir, threshold)
+            else:
+                print(f"Warning: Skipping invalid input (not a URL or existing file): {input_item}")
+
+        print(f"\nRunning analysis on outputs in {somef_output_dir}...")
+        run_analysis(somef_output_dir, args.pitfalls_output, args.analysis_output, verbose=args.verbose)
+
+
+if __name__ == "__main__":
+    cli()