RepoAuditor 0.2.3__tar.gz → 0.2.5__tar.gz

{repoauditor-0.2.3 → repoauditor-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RepoAuditor
-Version: 0.2.3
+Version: 0.2.5
 Summary: Add your description here
 Project-URL: Homepage, https://github.com/gt-sse-center/RepoAuditor
 Project-URL: Documentation, https://github.com/gt-sse-center/RepoAuditor
@@ -41,19 +41,71 @@ Description-Content-Type: text/markdown
 
 ## Contents
 - [Overview](#overview)
+  - [How to use RepoAuditor](#how-to-use-repoauditor)
+  - [Personal Access Token](#personal-access-token)
+  - [Example Usage](#example-usage)
 - [Installation](#installation)
 - [Development](#development)
 - [Additional Information](#additional-information)
 - [License](#license)
 
 ## Overview
-TODO: Complete this section
+
+We recommend using [uv](https://docs.astral.sh/uv/#uv) since `RepoAuditor` uses `uv` to create and manage a virtual environment.
 
 ### How to use RepoAuditor
-TODO: Complete this section
 
 <!-- Content below this delimiter will be copied to the generated README.md file. DO NOT REMOVE THIS COMMENT, as it will cause regeneration to fail. -->
 
+Once installed, you can invoke the following to verify if `RepoAuditor` is installed correctly:
+```shell
+uv run repo_auditor --version
+```
+and you should see something like
+```shell
+RepoAuditor vX.X.X
+```
+
+To get a list of command line options, you can run
+```shell
+uv run repo_auditor --help
+```
+
+### Personal Access Token (PAT)
+
+The most common use case for `RepoAuditor` would be to audit a GitHub repository.
+In order to allow `RepoAuditor` to read the repository, you first need to generate a Personal Access Token or PAT.
+
+Please refer to the [GitHub documentation on Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for details about a `Fine-grained PAT` which we will be using.
+
+To generate the Fine-grained PAT, we perform the following steps:
+
+1. Go to `Settings -> Developer settings -> Personal Access Token -> Fine-grained tokens`.
+2. Click on `Generate new token`.
+3. Give the token a name and a description.
+4. Set an appropriate expiration date.
+5. Under `Repository Access`, select `All repositories`.
+6. For permissions, we need to go to `Repository permissions`.
+7. Enable Read-Write access to `Contents`, and Read access to `Administration`, `Secret Scanning` and `Dependabot Alerts`.
+8. Click on `Generate token`.
+9. Copy the generated string. This is your PAT.
+
+After obtaining the PAT, you can save it in a file (e.g. `PAT`) which `RepoAuditor` can read on operation.
+
+### Example Usage
+
+With the above generated PAT file, you can now run `RepoAuditor` on your GitHub repository.
+As an example, we will use the [python-helloworld](https://github.com/dbarnett/python-helloworld) repo.
+
+**NOTE** You need to fork the repository since your default PAT only has access to repos under your account.
+
+To run `RepoAuditor`, we can enter the following in the command-line:
+```shell
+uv run repo_auditor --include GitHub --GitHub-url https://github.com/<username>/python-helloworld --GitHub-pat PAT
+```
+
+`RepoAuditor` will generate a series of messages describing all the issues in the repository, along with the rationale behind them and the steps for resolution.
+
 ## Installation
 
 | Installation Method | Command |
@@ -66,7 +118,9 @@ Artifacts are signed and validated using [py-minisign](https://github.com/x13a/p
 
 To verify that an artifact is valid, visit [the latest release](https://github.com/gt-sse-center/RepoAuditor/releases/latest) and download the `.minisign` signature file that corresponds to the artifact, then run the following command, replacing `<filename>` with the name of the artifact to be verified:
 
-`uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>')"`
+```shell
+uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>')"
+```
 
 ## Development
 Please visit [Contributing](https://github.com/gt-sse-center/RepoAuditor/blob/main/CONTRIBUTING.md) and [Development](https://github.com/gt-sse-center/RepoAuditor/blob/main/DEVELOPMENT.md) for information on contributing to this project.

{repoauditor-0.2.3 → repoauditor-0.2.5}/README.md

@@ -16,19 +16,71 @@
 
 ## Contents
 - [Overview](#overview)
+  - [How to use RepoAuditor](#how-to-use-repoauditor)
+  - [Personal Access Token](#personal-access-token)
+  - [Example Usage](#example-usage)
 - [Installation](#installation)
 - [Development](#development)
 - [Additional Information](#additional-information)
 - [License](#license)
 
 ## Overview
-TODO: Complete this section
+
+We recommend using [uv](https://docs.astral.sh/uv/#uv) since `RepoAuditor` uses `uv` to create and manage a virtual environment.
 
 ### How to use RepoAuditor
-TODO: Complete this section
 
 <!-- Content below this delimiter will be copied to the generated README.md file. DO NOT REMOVE THIS COMMENT, as it will cause regeneration to fail. -->
 
+Once installed, you can invoke the following to verify if `RepoAuditor` is installed correctly:
+```shell
+uv run repo_auditor --version
+```
+and you should see something like
+```shell
+RepoAuditor vX.X.X
+```
+
+To get a list of command line options, you can run
+```shell
+uv run repo_auditor --help
+```
+
+### Personal Access Token (PAT)
+
+The most common use case for `RepoAuditor` would be to audit a GitHub repository.
+In order to allow `RepoAuditor` to read the repository, you first need to generate a Personal Access Token or PAT.
+
+Please refer to the [GitHub documentation on Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for details about a `Fine-grained PAT` which we will be using.
+
+To generate the Fine-grained PAT, we perform the following steps:
+
+1. Go to `Settings -> Developer settings -> Personal Access Token -> Fine-grained tokens`.
+2. Click on `Generate new token`.
+3. Give the token a name and a description.
+4. Set an appropriate expiration date.
+5. Under `Repository Access`, select `All repositories`.
+6. For permissions, we need to go to `Repository permissions`.
+7. Enable Read-Write access to `Contents`, and Read access to `Administration`, `Secret Scanning` and `Dependabot Alerts`.
+8. Click on `Generate token`.
+9. Copy the generated string. This is your PAT.
+
+After obtaining the PAT, you can save it in a file (e.g. `PAT`) which `RepoAuditor` can read on operation.
+
+### Example Usage
+
+With the above generated PAT file, you can now run `RepoAuditor` on your GitHub repository.
+As an example, we will use the [python-helloworld](https://github.com/dbarnett/python-helloworld) repo.
+
+**NOTE** You need to fork the repository since your default PAT only has access to repos under your account.
+
+To run `RepoAuditor`, we can enter the following in the command-line:
+```shell
+uv run repo_auditor --include GitHub --GitHub-url https://github.com/<username>/python-helloworld --GitHub-pat PAT
+```
+
+`RepoAuditor` will generate a series of messages describing all the issues in the repository, along with the rationale behind them and the steps for resolution.
+
 ## Installation
 
 | Installation Method | Command |
@@ -41,7 +93,9 @@ Artifacts are signed and validated using [py-minisign](https://github.com/x13a/p
 
 To verify that an artifact is valid, visit [the latest release](https://github.com/gt-sse-center/RepoAuditor/releases/latest) and download the `.minisign` signature file that corresponds to the artifact, then run the following command, replacing `<filename>` with the name of the artifact to be verified:
 
-`uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>')"`
+```shell
+uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>')"
+```
 
 ## Development
 Please visit [Contributing](https://github.com/gt-sse-center/RepoAuditor/blob/main/CONTRIBUTING.md) and [Development](https://github.com/gt-sse-center/RepoAuditor/blob/main/DEVELOPMENT.md) for information on contributing to this project.

{repoauditor-0.2.3 → repoauditor-0.2.5}/pyproject.toml

@@ -47,6 +47,7 @@ build-backend = "hatchling.build"
 dev = [
     "autogitsemver>=0.8.0",
     "pre-commit>=4.2.0",
+    "pyfakefs>=5.8.0",
     "pytest>=8.3.5",
     "pytest-cov>=6.1.1",
     "ruff>=0.11.8",

{repoauditor-0.2.3 → repoauditor-0.2.5}/src/RepoAuditor/__init__.py

@@ -3,4 +3,4 @@ APP_NAME = "RepoAuditor"
 # Note that this value will be overwritten by calls to `python ../../Build.py update_version` based
 # on changes observed in the git repository. The default value below will be used until the value
 # here is explicitly updated by the Continuous Integration system.
-__version__ = "0.2.3"
+__version__ = "0.2.5"

repoauditor-0.2.5/tests/Plugins/GitHubModule_UnitTest.py

@@ -0,0 +1,69 @@
+# -------------------------------------------------------------------------------
+# |
+# |  Copyright (c) 2024 Scientific Software Engineering Center at Georgia Tech
+# |  Distributed under the MIT License.
+# |
+# -------------------------------------------------------------------------------
+"""Unit tests for GitHub/Module.py"""
+
+from pathlib import Path
+
+import pytest
+from pyfakefs.fake_filesystem_unittest import TestCase as FakeFSTestCase
+
+from RepoAuditor.Plugins.GitHub.Module import GitHubModule, _GitHubSession
+
+
+class TestGitHubSession(FakeFSTestCase):
+    """Unit tests for the _GitHubSession class."""
+
+    def setUp(self):
+        self.setUpPyfakefs()
+
+    def test_Construct(self):
+        """Test constructor."""
+        github_url = "https://github.com/gt-sse-center/RepoAuditor"
+
+        github_pat = Path(__file__).parent / "dummy_github_pat.txt"
+        self.fs.create_file(github_pat, contents="github_path_abcdefghijklmnop")
+
+        session = _GitHubSession(github_url=github_url, github_pat=github_pat)
+
+        assert session.github_url == github_url
+
+        # Test with trailing slash for URL
+        session = _GitHubSession(github_url=github_url + "/", github_pat=github_pat)
+
+        assert session.github_url == github_url
+
+        # Test with invalid repository
+        with pytest.raises(ValueError):
+            session = _GitHubSession(
+                github_url="https://github.com/gt-sse-center/RepoAuditor/123", github_pat=github_pat
+            )
+
+        # Test with enterprise URL
+        github_enterprise_url = "https://github.gatech.edu/gt-sse-center/RepoAuditor"
+        session = _GitHubSession(github_url=github_enterprise_url, github_pat=github_pat)
+        assert session.github_url == github_enterprise_url
+
+
+class TestGitHubModule:
+    """Unit tests for the Module class in the GitHub plugin."""
+
+    def test_Construct(self):
+        """Test constructor."""
+        module = GitHubModule()
+        assert isinstance(module, GitHubModule)
+
+    def test_GenerateInitialData(self):
+        """Test GenerateInitialData method."""
+        dynamic_args = {
+            "url": "https://github.com/gt-sse-center/RepoAuditor",
+            "pat": Path(__file__).parent / "dummy_github_pat.txt",
+        }
+        module = GitHubModule()
+        dynamic_args = module.GenerateInitialData(dynamic_args)
+
+        assert "session" in dynamic_args
+        assert isinstance(dynamic_args["session"], _GitHubSession)

{repoauditor-0.2.3 → repoauditor-0.2.5}/uv.lock

@@ -392,6 +392,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/88/74/a88bf1b1efeae488a0c0b7bdf71429c313722d1fc0f377537fbe554e6180/pre_commit-4.2.0-py2.py3-none-any.whl", hash = "sha256:a009ca7205f1eb497d10b845e52c838a98b6cdd2102a6c8e4540e94ee75c58bd", size = 220707, upload-time = "2025-03-18T21:35:19.343Z" },
 ]
 
+[[package]]
+name = "pyfakefs"
+version = "5.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a8/50/a839c8812899e8955223d95b27767480856f9723b3230ddee0472cf1dbe2/pyfakefs-5.8.0.tar.gz", hash = "sha256:7e5457ee3cc67069d3cef6e278227ecfc80bfb61e925bc0a4d3b0af32d1c99ce", size = 215072, upload-time = "2025-03-11T19:29:20.274Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/14/ac/ae2cf01b18b7ac04d22e5faf7d5eafcc000269c4f4a9036e40da6c37aed9/pyfakefs-5.8.0-py3-none-any.whl", hash = "sha256:4bd0fc8def7d0582139922447758632ff34a327b460a7e83feb6edbd841061dd", size = 230606, upload-time = "2025-03-11T19:29:18.341Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.19.1"
@@ -503,6 +512,7 @@ dependencies = [
 dev = [
     { name = "autogitsemver" },
     { name = "pre-commit" },
+    { name = "pyfakefs" },
     { name = "pytest" },
     { name = "pytest-cov" },
     { name = "ruff" },
@@ -521,6 +531,7 @@ requires-dist = [
 dev = [
     { name = "autogitsemver", specifier = ">=0.8.0" },
     { name = "pre-commit", specifier = ">=4.2.0" },
+    { name = "pyfakefs", specifier = ">=5.8.0" },
     { name = "pytest", specifier = ">=8.3.5" },
     { name = "pytest-cov", specifier = ">=6.1.1" },
     { name = "ruff", specifier = ">=0.11.8" },