RepoAuditor 0.2.82__tar.gz → 0.2.84__tar.gz

{repoauditor-0.2.82 → repoauditor-0.2.84}/.gitignore

@@ -28,3 +28,6 @@ post_generation_instructions.html
 
 # Test coverage report
 **/coverage.xml
+
+# Documentation site
+site/

repoauditor-0.2.84/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: RepoAuditor
+Version: 0.2.84
+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
+Project-URL: Repository, https://github.com/gt-sse-center/RepoAuditor
+Author-email: Scientific Software Engineering Center at Georgia Tech <sse-center@gatech.edu>
+License: MIT
+License-File: LICENSE
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: dbrownell-common>=0.16.0
+Requires-Dist: gitpython>=3.1.44
+Requires-Dist: pluggy>=1.5.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: typer-config[yaml]>=1.4.2
+Requires-Dist: typer>=0.15.3
+Description-Content-Type: text/markdown
+
+# RepoAuditor - README
+
+**Project:**
+[![License](https://img.shields.io/github/license/gt-sse-center/RepoAuditor?color=dark-green)](https://github.com/gt-sse-center/RepoAuditor/blob/master/LICENSE)
+
+**Package:**
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/repoauditor?color=dark-green)](https://pypi.org/project/repoauditor/)
+[![PyPI - Version](https://img.shields.io/pypi/v/repoauditor?color=dark-green)](https://pypi.org/project/repoauditor/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/repoauditor)](https://pypistats.org/packages/repoauditor)
+
+**Development:**
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![CI](https://github.com/gt-sse-center/RepoAuditor/actions/workflows/CICD.yml/badge.svg)](https://github.com/gt-sse-center/RepoAuditor/actions/workflows/CICD.yml)
+[![Code Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/davidbrownell/2f9d770d13e3a148424f374f74d41f4b/raw/RepoAuditor_code_coverage.json)](https://github.com/gt-sse-center/RepoAuditor/actions)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/gt-sse-center/RepoAuditor?color=dark-green)](https://github.com/gt-sse-center/RepoAuditor/commits/main/)
+
+<!-- Content above this delimiter will be copied to the generated README.md file. DO NOT REMOVE THIS COMMENT, as it will cause regeneration to fail. -->
+
+## Overview
+
+`RepoAuditor` is a tool which audits repositories for best practices.
+
+If you're running an open-source repository, there are many steps involved in being open-source beyond making your repository public.
+
+In order to make your repository both friendly to maintainers and contributors, you will want to enable/disable some settings (e.g. require reviews, status checks pass), or you may be missing certains files (like `LICENSE` or `CODE_OF_CONDUCT`) that prevent adoption of your project.
+
+`RepoAuditor` can check and audit your repository so that all the right settings and content are available to make your open-source repository high-quality, even if you are new to maintaining one.
+
+E.g. check if various files for maintaining community standards are available:
+
+```shell
+uvx repoauditor --include CommunityStandards \
+    --CommunityStandards-url https://github.com/gt-sse-center/RepoAuditor \
+    --verbose
+```
+
+This will check if your open-source repository has files like a License, Code of Conduct, README, Code Owners, etc.
+
+We have set `RepoAuditor` to have defaults which match with best practices in open-source communities, however they can all be overrided.
+
+For more information on how to use `RepoAuditor` and its available features, please refer to the documentation below.
+
+## Documentation
+
+Please refer to the documentation hosted [here](docs/index.md).
+
+## Development
+
+Please visit [Contributing](https://github.com/gt-sse-center/RepoAuditor/blob/main/docs/CONTRIBUTING.md) and [Development](https://github.com/gt-sse-center/RepoAuditor/blob/docs/development.md) for information on contributing to this project.
+
+## Additional Information
+
+Additional information can be found at these locations.
+
+| Title | Document | Description |
+| --- | --- | --- |
+| Code of Conduct | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Information about the norms, rules, and responsibilities we adhere to when participating in this open source community. |
+| Contributing | [CONTRIBUTING.md](docs/CONTRIBUTING.md) | Information about contributing to this project. |
+| Development | [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Information about development activities involved in making changes to this project. |
+| Governance | [GOVERNANCE.md](GOVERNANCE.md) | Information about how this project is governed. |
+| Maintainers | [MAINTAINERS.md](MAINTAINERS.md) | Information about individuals who maintain this project. |
+| Security | [SECURITY.md](SECURITY.md) | Information about how to privately report security issues associated with this project. |
+
+## License
+
+RepoAuditor is licensed under the <a href="https://choosealicense.com/licenses/MIT/" target="_blank">MIT</a> license.

repoauditor-0.2.84/README.md

@@ -0,0 +1,66 @@
+# RepoAuditor - README
+
+**Project:**
+[![License](https://img.shields.io/github/license/gt-sse-center/RepoAuditor?color=dark-green)](https://github.com/gt-sse-center/RepoAuditor/blob/master/LICENSE)
+
+**Package:**
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/repoauditor?color=dark-green)](https://pypi.org/project/repoauditor/)
+[![PyPI - Version](https://img.shields.io/pypi/v/repoauditor?color=dark-green)](https://pypi.org/project/repoauditor/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/repoauditor)](https://pypistats.org/packages/repoauditor)
+
+**Development:**
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![CI](https://github.com/gt-sse-center/RepoAuditor/actions/workflows/CICD.yml/badge.svg)](https://github.com/gt-sse-center/RepoAuditor/actions/workflows/CICD.yml)
+[![Code Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/davidbrownell/2f9d770d13e3a148424f374f74d41f4b/raw/RepoAuditor_code_coverage.json)](https://github.com/gt-sse-center/RepoAuditor/actions)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/gt-sse-center/RepoAuditor?color=dark-green)](https://github.com/gt-sse-center/RepoAuditor/commits/main/)
+
+<!-- Content above this delimiter will be copied to the generated README.md file. DO NOT REMOVE THIS COMMENT, as it will cause regeneration to fail. -->
+
+## Overview
+
+`RepoAuditor` is a tool which audits repositories for best practices.
+
+If you're running an open-source repository, there are many steps involved in being open-source beyond making your repository public.
+
+In order to make your repository both friendly to maintainers and contributors, you will want to enable/disable some settings (e.g. require reviews, status checks pass), or you may be missing certains files (like `LICENSE` or `CODE_OF_CONDUCT`) that prevent adoption of your project.
+
+`RepoAuditor` can check and audit your repository so that all the right settings and content are available to make your open-source repository high-quality, even if you are new to maintaining one.
+
+E.g. check if various files for maintaining community standards are available:
+
+```shell
+uvx repoauditor --include CommunityStandards \
+    --CommunityStandards-url https://github.com/gt-sse-center/RepoAuditor \
+    --verbose
+```
+
+This will check if your open-source repository has files like a License, Code of Conduct, README, Code Owners, etc.
+
+We have set `RepoAuditor` to have defaults which match with best practices in open-source communities, however they can all be overrided.
+
+For more information on how to use `RepoAuditor` and its available features, please refer to the documentation below.
+
+## Documentation
+
+Please refer to the documentation hosted [here](docs/index.md).
+
+## Development
+
+Please visit [Contributing](https://github.com/gt-sse-center/RepoAuditor/blob/main/docs/CONTRIBUTING.md) and [Development](https://github.com/gt-sse-center/RepoAuditor/blob/docs/development.md) for information on contributing to this project.
+
+## Additional Information
+
+Additional information can be found at these locations.
+
+| Title | Document | Description |
+| --- | --- | --- |
+| Code of Conduct | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Information about the norms, rules, and responsibilities we adhere to when participating in this open source community. |
+| Contributing | [CONTRIBUTING.md](docs/CONTRIBUTING.md) | Information about contributing to this project. |
+| Development | [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Information about development activities involved in making changes to this project. |
+| Governance | [GOVERNANCE.md](GOVERNANCE.md) | Information about how this project is governed. |
+| Maintainers | [MAINTAINERS.md](MAINTAINERS.md) | Information about individuals who maintain this project. |
+| Security | [SECURITY.md](SECURITY.md) | Information about how to privately report security issues associated with this project. |
+
+## License
+
+RepoAuditor is licensed under the <a href="https://choosealicense.com/licenses/MIT/" target="_blank">MIT</a> license.

repoauditor-0.2.84/default_config.yaml

@@ -0,0 +1,5 @@
+includes: ["GitHub", "CommunityStandards"]  # Note that `includes` is plural compared to the CLI, since is accepts a list
+excludes: []  # Similarly, `excludes` is plural.
+GitHub-url: "https://github.com/gt-sse-center/RepoAuditor"
+CommunityStandards-url: "https://github.com/gt-sse-center/RepoAuditor"
+# GitHub-pat: "PAT"

{repoauditor-0.2.82 → repoauditor-0.2.84/docs}/CONTRIBUTING.md

@@ -4,17 +4,20 @@ Additional information is available at the following locations.
 
 | Topic | Description | Location |
 | --- | --- | --- |
-| Code of Conduct | How we welcome others to this community. | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
-| Development Activities | How we create software in this community. | [DEVELOPMENT.md](DEVELOPMENT.md) |
-| Security | How to report vulnerabilities in our software. | [SECURITY.md](SECURITY.md) |
+| Code of Conduct | How we welcome others to this community. | [CODE_OF_CONDUCT.md](https://github.com/gt-sse-center/RepoAuditor/blob/main/CODE_OF_CONDUCT.md) |
+| Development Activities | How we create software in this community. | [DEVELOPMENT.md](https://github.com/gt-sse-center/RepoAuditor/blob/main/DEVELOPMENT.md) |
+| Security | How to report vulnerabilities in our software. | [SECURITY.md](https://github.com/gt-sse-center/RepoAuditor/blob/main/SECURITY.md) |
+
+## Bug Reports
 
-# Bug Reports
 If you experience a problem with our software, please visit [issues](https://github.com/gt-sse-center/RepoAuditor/issues) and create a `Bug report`.
 
-# Feature Requests
+## Feature Requests
+
 If you would like to suggest a new feature for our software, please visit [issues](https://github.com/gt-sse-center/RepoAuditor/issues) and create a `Feature request`.
 
-# Issue Labels
+## Issue Labels
+
 We use these labels to help us track and manage `Bug reports` and `Feature requests`.
 
 | Label | Description |
@@ -25,7 +28,8 @@ We use these labels to help us track and manage `Bug reports` and `Feature reque
 | `good first issue` | Good for newcomers. |
 | `documentation` | Improvements or additions to documentation. |
 
-## General information
+## General Information
+
 <!-- [BEGIN] General Information -->
 For specific proposals, please provide them as [pull requests](https://github.com/coreinfrastructure/best-practices-badge/pulls) or [issues](https://github.com/coreinfrastructure/best-practices-badge/issues) via our [GitHub site](https://github.com/gt-sse-center/RepoAuditor).
 <!-- [END] General Information -->
@@ -33,6 +37,7 @@ For specific proposals, please provide them as [pull requests](https://github.co
 The [DEVELOPMENT.md](DEVELOPMENT.md) file explains how to install the program locally (highly recommended if you're going to make code changes). It also provides information useful for making changes and validating them locally before submitting a pull request.
 
 ### Pull requests and different branches recommended
+
 <!-- [BEGIN] Pull Requests and Branches -->
 Pull requests are preferred, since they are specific. For more about how to create a pull request, see https://help.github.com/articles/using-pull-requests/.
 
@@ -40,19 +45,22 @@ We recommend creating different branches for different (logical) changes, and cr
 <!-- [END] Pull Requests and Branches -->
 
 ### How we handle proposals
+
 <!-- [BEGIN] Proposals -->
 We use GitHub to track proposed changes via its [issue tracker](https://github.com/coreinfrastructure/best-practices-badge/issues) and [pull requests](https://github.com/coreinfrastructure/best-practices-badge/pulls). Specific changes are proposed using those mechanisms. Issues are assigned to an individual, who works and then marks it complete. If there are questions or objections, the conversation of that issue or pull request is used to resolve it.
 <!-- [END] Proposals -->
 
 ### We are proactive
+
 In general we try to be proactive to detect and eliminate mistakes and vulnerabilities as soon as possible, and to reduce their impact when they do happen. We use a defensive design and coding style to reduce the likelihood of mistakes, a variety of tools that try to detect mistakes early, and an automatic test suite with significant coverage. We also release the software as open source software so others can review it.
 
 Since early detection and impact reduction can never be perfect, we also try to detect and repair problems during deployment as quickly as possible. This is especially true for security issues; see our [security information](#vulnerability-reporting-security-issues) for more information.
 
 ## Vulnerability reporting (security issues)
+
 Please privately report vulnerabilities you find so we can fix them!
 
-See [SECURITY.md](SECURITY.md) for information on how to privately report vulnerabilities.
+See [SECURITY.md](https://github.com/gt-sse-center/RepoAuditor/blob/main/SECURITY.md) for information on how to privately report vulnerabilities.
 
 ## Acknowledgements
 

{repoauditor-0.2.82 → repoauditor-0.2.84/docs}/DEVELOPMENT.md

@@ -1,11 +1,11 @@
-# DEVELOPMENT GUIDE
+# Development Guide
 
 ## Fork setup
 
 | Step | Command Line | Additional Information |
 | --- | --- | --- |
-| 1. Fork the repository | -- | https://github.com/gt-sse-center/RepoAuditor/fork |
-| 2. Create a PAT for your forked repository | -- | See [PAT setup instructions](README.md#personal-access-token-pat) |
+| 1. Fork the repository | -- | [Fork Link](https://github.com/gt-sse-center/RepoAuditor/fork) |
+| 2. Create a PAT for your forked repository | -- | See [PAT setup instructions](PAT.md) |
 | 3. Update your forked repository settings to match RepoAuditor's defaults | -- | -- |
 
 ## Local Development
@@ -14,10 +14,10 @@
 
 | Step | Command Line | Additional Information |
 | --- | --- | --- |
-| 1. Clone the repository locally. | `git clone https://github.com/gt-sse-center/RepoAuditor` | https://git-scm.com/docs/git-clone |
+| 1. Clone the repository locally. | `git clone https://github.com/gt-sse-center/RepoAuditor` | [git-clone docs](https://git-scm.com/docs/git-clone) |
 | 2. Install [uv](https://github.com/astral-sh/uv). | `curl -LsSf https://astral.sh/uv/install.sh \| sh` on macOS and Linux or <br/>`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` on Windows | https://docs.astral.sh |
-| 3. Install dependencies. | `uv sync` | https://docs.astral.sh/uv/concepts/projects/sync |
-| 4. Install [pre-commit](https://pre-commit.com/) hooks | `uv run pre-commit install` | https://pre-commit.com/#1-install-pre-commit |
+| 3. Install dependencies. | `uv sync` | [Astral uv sync docs](https://docs.astral.sh/uv/concepts/projects/sync) |
+| 4. Install [pre-commit](https://pre-commit.com/) hooks | `uv run pre-commit install` | [Install pre-commit](https://pre-commit.com/#1-install-pre-commit) |
 | 5. If you wish to test against an enterprise server, add a remote named `enterprise` with the corresponding URL | E.g. `git remote add enterprise git@github.gatech.edu:sse-center/RepoAuditor.git` | |
 
 ### Setup
@@ -30,16 +30,16 @@ Please follow these steps to allow for local testing.
 - Create a PAT file as detailed in the [README](https://github.com/gt-sse-center/RepoAuditor/blob/main/README.md#personal-access-token-pat).
 - Set your forked repository as the `origin` remote (this should already be the case but it's good to verify).
 
-  ```sh
-  git remote add origin git@github.com:<github-username>/RepoAuditor.git
-  ```
+```sh
+git remote add origin git@github.com:<github-username>/RepoAuditor.git
+```
 
 - Update the URL in `default_config.yaml` to point to your fork.
 - You should now be able to run the following and see valid output. There will be errors, which we will tackle next.
 
-  ```sh
-  uv run RepoAuditor --config default_config.yaml --GitHub-pat PAT.txt
-  ```
+```sh
+uv run RepoAuditor --config default_config.yaml --GitHub-pat PAT.txt
+```
 
 #### Local Testing
 
@@ -136,6 +136,23 @@ 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:
 
-```shell
+```sh
 uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>')"
-```
+```
+
+### Generating Documentation
+
+We use [MkDocs](https://www.mkdocs.org/) to generate the documentation website.
+To generate the docs, please run
+
+```sh
+uv run mkdocs --serve
+```
+
+and go to the specified URL.
+
+To publish the website using [GitHub pages](https://docs.github.com/en/pages), you can simply run
+
+```sh
+uv run mkdocs gh-deploy
+```

repoauditor-0.2.84/docs/PAT.md

@@ -0,0 +1,27 @@
+# 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 the following permissions:
+    - Read-Write access to `Contents`.
+    - Read access to `Administration` and `Secret scanning alerts`.
+8. Click on `Generate token`.
+9. Copy the generated string. This is your PAT.
+10. Save the PAT to a convenient location on your machine (such as your home directory `~/`) in the file `PAT.txt`.
+
+The path to the `PAT.txt` will be passed into `RepoAuditor`. E.g.
+
+```sh
+uvx RepoAuditor --GitHub-pat ~/PAT.txt
+```

repoauditor-0.2.84/docs/config_file.md

@@ -0,0 +1,52 @@
+# Configuration File
+
+`RepoAuditor` accepts both a set of flags as well as a configuration YAML file.
+
+The configuration (or config) file can make usage easier by recording preferences as well as facilitating sharing of enforced requirements within an organization.
+We have provided a sample configuration file called [default_config.yaml](https://github.com/gt-sse-center/RepoAuditor/blob/main/default_config.yaml), which can be used as:
+
+```sh
+uvx RepoAuditor --config default_config.yaml
+```
+
+## Key Differences
+
+There are some differences between the flags used in the CLI and the options provided in the config file.
+
+### Multiple Values
+
+For example, to include multiple module on the CLI, the user would use the `--include` multiple times.
+
+```sh
+uvx RepoAuditor --include CommunityStandards --include GitHub
+```
+
+However, since the config file accepts a list of values, the corresponding option is `includes` (which is plural).
+
+```yaml
+includes: ["GitHub", "CommunityStandards"]
+```
+
+This is similarly the case for `--exclude` on the CLI and `excludes` in the config file.
+
+### Boolean Flags
+
+On the CLI, the existence of a boolean flag, e.g. `--GitHub-Description-allow-empty` is sufficient to indicate that we want this setting to be enabled.
+
+However since YAML files expect key-value pairs, in the config file, you will have to specify the same flag as:
+
+```yaml
+GitHub-Description-allow-empty: true
+```
+
+Similarly for the case where we wish to check a setting is turned off, we specify e.g. `--GitHub-no-MergeCommit` on the CLI, but in the config file, it would be
+
+```yaml
+GitHub-no-MergeCommit: true
+```
+
+Remember, to deactive a check, we have to add the `Module-Requirement` to the `excludes` list,
+
+```yaml
+excludes: ["GitHub-MergeCommit"]
+```

repoauditor-0.2.84/docs/index.md

@@ -0,0 +1,55 @@
+# RepoAuditor
+
+`RepoAuditor` is a handy tool which audits repositories for best practices.
+
+It helps maintain high-quality and consistent open-source repositories even if you are new to maintaining open-source software.
+
+## Contents
+
+- [Installation](#installation)
+- [How to use RepoAuditor](#how-to-use)
+- [Personal Access Token](PAT.md)
+- [Example Usage](usage.md)
+- [Config File](config_file.md)
+- [Development](development)
+
+## Installation
+
+We recommend using [uv](https://docs.astral.sh/uv/#uv) since it can install `RepoAuditor` as a tool via `uvx` into a sandbox environment for quick use.
+This lets you directly run `RepoAuditor`.
+
+```sh
+uvx RepoAuditor
+```
+
+Alternatively, you can install `RepoAuditor` via `uv` or `pip`.
+`uv` is preferred to `pip` since it creates and manages a virtual environment.
+
+| Installation Method | Command |
+| --- | --- |
+| Via [uv](https://github.com/astral-sh/uv) | `uv add repoauditor` |
+| Via [pip](https://pip.pypa.io/en/stable/) | `pip install repoauditor` |
+
+## How To Use
+
+Once installed, you can invoke the following to verify if `RepoAuditor` is installed correctly:
+
+```sh
+uvx RepoAuditor --version
+```
+
+and you should see something like
+
+```sh
+RepoAuditor vX.X.X
+```
+
+To get a list of command line options, you can run
+
+```sh
+uvx RepoAuditor --help
+```
+
+In order to use `RepoAuditor` with GitHub, you will need a Personal Access Token (or PAT for short).
+
+Let's go over how to [generate a PAT next](PAT.md).

repoauditor-0.2.84/docs/troubleshooting.md

@@ -0,0 +1 @@
+# Troubleshooting Guide

repoauditor-0.2.84/docs/usage.md

@@ -0,0 +1,98 @@
+# Usage
+
+## Basic Use
+
+With a generated PAT file, you can now run `RepoAuditor` on your GitHub repository.
+
+```sh
+uvx repoauditor --include GitHub \
+  --GitHub-url <url-to-repo> \
+  --GitHub-pat ~/PAT.txt
+```
+
+If your repository is on an enterprise server, you can similarly generate a PAT (and save it `enterprise_PAT.txt`) and point `RepoAuditor` to the corresponding repo:
+
+```sh
+uvx repoauditor --include GitHub \
+  --GitHub-url <url-to-enterprise-repo> \
+  --GitHub-pat ~/enterprise_PAT.txt
+```
+
+As a general example, we will use the [python-helloworld](https://github.com/dbarnett/python-helloworld) repository.
+
+> **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:
+
+```sh
+uvx repoauditor --include GitHub \
+  --GitHub-url https://github.com/<username>/python-helloworld \
+  --GitHub-pat ~/PAT.txt
+```
+
+`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.
+
+<br/>
+
+## Custom Settings
+
+`RepoAuditor` tries to provide default settings and checks which are considered best practices. However, your team or organization may have different ways of doing things.
+You can override the default settings by specifying the appropriate flag.
+
+We have 3 types of flags:
+
+1. Boolean flags for those settings which are checked to be on by default and you wish to check are off, with the form `Module-no-Requirement` (e.g. `--GitHub-no-MergeCommit`).
+2. Conversely, boolean flags for those settings which are checked to be off by default, and you wish to check are on, denoted by the form `Module-Requirement` (e.g. `--GitHub-AllowDeletions`).
+3. Values flags take a string value to determine what value to enforce, and have the form `Module-Requirement-value` (e.g. `--GitHub-License-value "MIT License"`).
+
+Please run `uvx repoauditor --help` to get the list of all flags available.
+
+<br/>
+
+## Examples
+
+In this section, we will look at various exampls of using `RepoAuditor`. For the sake of brevity, we will omit the `--include` and `--GitHub-url` flags, leaving the inclusion to the user.
+
+`RepoAuditor` is designed to have sensible defaults which represent industry best practices.
+For example, `RepoAuditor` by default checks that the setting `Allow rebase merging` is off. However, if you wish to check that this setting is turned on, you can run:
+
+```sh
+uvx repoauditor --GitHub-RebaseMergeCommit
+```
+
+Similarly, `RepoAuditor` checks if `Issues` are enabled. You can set `RepoAuditor` to check if `Issues` is disabled by specifying
+
+```sh
+uvx repoauditor --GitHub-no-SupportIssues
+```
+
+Finally, `RepoAuditor` by default enforces that the `MIT License` exists for the repository. If your organization requires another license (such as `GPL`), you can enforce that by specifying the license keyword such as:
+
+```sh
+uvx repoauditor --GitHub-License-value "GNU General Public License v2.0"
+```
+
+The types of licenses supported by GitHub can be found [here](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository#searching-github-by-license-type). Be sure to specify the full license name, e.g. `GNU General Public License v2.0`.
+
+<br/>
+
+## Excluding Requirements
+
+There is often the case you might wish to exclude a module or a specific requirement.
+`RepoAuditor` has built-in support for this as well, by using the `--exclude` flag.
+
+To exclude a requirement, you can run specify the requirement as `Module-Requirement`
+
+```sh
+uvx repoauditor --include GitHub --exclude GitHub-RequireSignedCommitsRule
+```
+
+The above command includes all of the requirements in the `GitHub` module except for the `RequireSignedCommitsRule` requirement.
+
+You can similarly exclude a whole module:
+
+```sh
+uvx repoauditor --include GitHub --exclude CommunityStandards
+```
+
+NOTE: This way of excluding a module is redundant since any module not added via `--include` is automatically excluded.

repoauditor-0.2.84/mkdocs.yml

@@ -0,0 +1,23 @@
+site_name: RepoAuditor
+site_description: Audits repositories for best practices.
+nav:
+  - Home: index.md
+  - PAT: PAT.md
+  - Usage: usage.md
+  - Config File: config_file.md
+  - Development: DEVELOPMENT.md
+  - Contributing: CONTRIBUTING.md
+  - Troubleshooting: troubleshooting.md
+theme:
+  name: material
+  palette:
+    scheme: slate
+    primary: teal
+    accent: lime
+
+
+# Extensions to render emojis
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg

{repoauditor-0.2.82 → repoauditor-0.2.84}/pyproject.toml

@@ -55,6 +55,7 @@ dev = [
     "pytest-cov>=6.1.1",
     "ruff>=0.11.8",
     "syrupy>=4.9.1",
+    "mkdocs-material>=9.6.16",
 ]
 
 [tool.hatch.version]

{repoauditor-0.2.82 → repoauditor-0.2.84}/src/RepoAuditor/Plugins/GitHub/DefaultBranchRequirements/Protected.py

@@ -76,7 +76,7 @@ class Protected(Requirement):
     ) -> Requirement.EvaluateImplResult:
         is_protected = query_data["default_branch_data"].get("protected", None)
         if is_protected is None:
-            return CreateIncompleteDataResult()
+            return CreateIncompleteDataResult(query_data["pat"] is not None)
 
         if requirement_args["no"]:
             expected_value = False

repoauditor-0.2.84/src/RepoAuditor/Plugins/GitHub/Impl/Common.py

@@ -0,0 +1,34 @@
+# -------------------------------------------------------------------------------
+# |
+# |  Copyright (c) 2024 Scientific Software Engineering Center at Georgia Tech
+# |  Distributed under the MIT License.
+# |
+# -------------------------------------------------------------------------------
+"""Contains common functionality that is used across different components."""
+
+from RepoAuditor.Requirement import EvaluateResult, Requirement
+
+
+# ----------------------------------------------------------------------
+def CreateIncompleteDataResult(pat_value_exists: bool) -> Requirement.EvaluateImplResult:  # noqa: FBT001
+    """Create an incomplete data result.
+
+    Checks if the PAT value is `None` to generate additional message info.
+
+    Args:
+        pat_value_exists (bool): The value of the Personal Access Token.
+
+    Returns:
+        Requirement.EvaluateImplResult: A warning result notifying the user of an incomplete result.
+
+    """
+    error_message = "Incomplete data was encountered."
+    if pat_value_exists:
+        error_message += "\nPlease update the permissions of the GitHub PAT."
+    else:
+        error_message += "\nGitHub PAT was not provided. Please provide the PAT."
+
+    return Requirement.EvaluateImplResult(
+        EvaluateResult.Warning,
+        error_message,
+    )

{repoauditor-0.2.82 → repoauditor-0.2.84}/src/RepoAuditor/Plugins/GitHub/Impl/EnableRequirementImpl.py

@@ -103,7 +103,7 @@ class EnableRequirementImpl(Requirement):
                 )
 
             if self.missing_value_is_warning:
-                return CreateIncompleteDataResult()
+                return CreateIncompleteDataResult(query_data["pat"] is not None)
 
             return Requirement.EvaluateImplResult(EvaluateResult.DoesNotApply, None)
 

{repoauditor-0.2.82 → repoauditor-0.2.84}/src/RepoAuditor/Plugins/GitHub/Impl/ValueRequirementImpl.py

@@ -90,7 +90,7 @@ class ValueRequirementImpl(Requirement):
         result = self.get_configuration_value_func(query_data)
         if result is None:
             if self.missing_value_is_warning:
-                return CreateIncompleteDataResult()
+                return CreateIncompleteDataResult(query_data["pat"] is not None)
 
             return Requirement.EvaluateImplResult(EvaluateResult.DoesNotApply, None)