Merge pull request #179 from advanced-security/project-update

Project Update

Author: GeekMasher

.github/dependabot.yml

@@ -10,7 +10,7 @@ updates:
     schedule:
       interval: "weekly"
     reviewers:
-      - "geekmasher"
+      - "advanced-security/oss-maintainers"
     target-branch: "main"
     commit-message:
       prefix: deps
@@ -28,7 +28,7 @@ updates:
     schedule:
       interval: "weekly"
     reviewers:
-      - "geekmasher"
+      - "advanced-security/oss-maintainers"
     target-branch: "main"
     commit-message:
       prefix: deps

.github/instructions/project.instructions.md

@@ -0,0 +1,41 @@
+---
+applyTo: "**/*.py"
+---
+
+This project is a Python CLI and GitHub Action policy-as-code engine and toolkit.
+It uses Python 3.10+ and Pipenv for dependency management, Black for code formatting, and unittest for testing.
+
+## Coding Guidelines
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) style guidelines.
+- Use type hints for all function signatures.
+- Write clear, concise docstrings for all public functions and classes.
+- Use `os.path.join()` for all path concatenations.
+- Prefer f-strings for string interpolation.
+- Ensure cross-platform compatibility (Linux, macOS, Windows).
+- Avoid hardcoding paths or platform-specific logic.
+- Keep functions small and focused; prefer composition over inheritance.
+
+## Testing & Quality
+
+- Write unit tests for all new features and bug fixes.
+- Ensure all tests pass before committing code.
+- Maintain good test coverage; aim for 90%+ where practical.
+- Use descriptive test names and keep tests isolated.
+
+**Run tests with:**
+
+```bash
+pipenv run test
+```
+
+**Format code before committing:**
+
+```bash
+pipenv run fmt
+```
+
+## Documentation
+
+- Document all public APIs and modules with docstrings.
+- Update Sphinx documentation in `docs/` for new features or changes.

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing Guide
+
+Thank you for your interest in contributing to Policy as Code!
+
+## Getting Started
+
+- Ensure you have Python 3.9+ and [Pipenv](https://pipenv.pypa.io/en/latest/) installed.
+
+**Install dependencies:**
+
+```bash
+pipenv install --dev
+```
+
+**Run the CLI:**
+
+```bash
+pipenv run main --help
+```
+
+## Code Style
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) guidelines.
+- Use type hints and docstrings for all functions.
+- Use `os.path.join()` for paths and f-strings for formatting.
+
+**Format code with Black:**
+
+```bash
+pipenv run fmt
+```
+
+## Testing
+
+- Write unit tests for all new features and bug fixes.
+- Ensure all tests pass before submitting a pull request:
+
+```bash
+pipenv run test
+```
+
+## Markdown Linting
+
+- Markdown files should adhere to standard conventions.
+- Use a Markdown linter `markdownlint`
+
+Use the following comments to run the linter:
+
+```bash
+markdownlint '**.md' --disable MD013
+```
+
+## Vendoring Dependencies
+
+- Dependencies are vendored in the `vendor/` directory for reliability and security. See [vendor/README.md](./vendor/README.md).
+- To update or add dependencies:
+  1. Add or update the dependency using Pipenv.
+
+```bash
+pipenv run vendor
+```
+
+## Submitting Changes
+
+1. Fork the repository and create a feature branch.
+2. Make your changes, following the guidelines above.
+3. Run tests and ensure code is formatted.
+4. Submit a pull request with a clear description of your changes.
+
+## Community & Support
+
+- Please follow our [Code of Conduct](./CODE_OF_CONDUCT.md).
+- For help, see [SUPPORT.md](./SUPPORT.md) or open a GitHub Issue.

README.md

@@ -13,10 +13,12 @@
 
 ## Overview
 
-[GitHub's Policy as Code][github] project is designed to allow users and organizations to configure their Risk
-threshold for security issues reported by GitHub Advanced Security Platform.
-The main goal is to help make sure that before publishing your application to productions, development, etc.
-you can validate if the application has any security issues that need to be addressed.
+[GitHub's Policy as Code][github] project is designed to allow users and organizations to configure their Risk threshold for security issues reported by GitHub Advanced Security Platform.
+The main goal is to help make sure that before publishing your application to productions, development, etc. you can validate if the application has any security issues that need to be addressed.
+
+Policy as Code lets you define compliance and risk rules for your repositories using YAML configuration files.
+It supports code scanning, secret scanning, dependency checks, licensing, and more.
+You can run it as a GitHub Action or locally via CLI.
 
 ## ✨ Features
 
@@ -29,9 +31,26 @@ you can validate if the application has any security issues that need to be addr
 - Supports GitHub Enterprise Cloud or Server ([see supported features list](#supported-features))
 - Pull Request Summary
 
+## 💡 Key Features
+
+- **Highly Configurable:** Write custom rules for your organization or repository.
+- **Multi-Platform:** Works with GitHub.com and GitHub Enterprise Server.
+- **Comprehensive Security:** Supports code scanning, secret scanning, dependency and license checks.
+- **Pull Request Summaries:** Adds compliance results to PRs.
+- **Vendored Dependencies:** All Python dependencies are included for reliability.
+- **Extensive Examples:** See [`examples/policies/`](./examples/policies/) and [`examples/workflows/`](./examples/workflows/).
+
 ## ⚡️ Requirements
 
-- Python +3.9
+- Python >= 3.9
+
+## 📦 Project Structure
+
+- `ghascompliance/` — Main Python source code
+- `examples/` — Example policies, workflows, and scripts
+- `tests/` — Unit tests
+- `docs/` — Sphinx documentation
+- `vendor/` — Vendored Python dependencies
 
 ## Usage
 
@@ -294,6 +313,11 @@ Some things to consider when using imports:
   - `Cloned Repository Directory`
 - Imports are only allowed from a number of predefined paths to prevent loading data on the system (AKA, path traversal).
 
+## 🛠️ Development & Contributing
+
+We welcome contributions from the community!
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on setting up your environment, code style, testing, and submitting changes.
+
 ## Maintainers / Contributors
 
 - [@GeekMasher](https://github.com/GeekMasher) - Author / Core Maintainer
@@ -315,17 +339,14 @@ Please refer to [MIT][license] for the full terms.
 [github]: https://github.com/advanced-security/policy-as-code
 [github-issues]: https://github.com/advanced-security/policy-as-code/issues
 [github-actions]: https://github.com/advanced-security/policy-as-code/actions
-
 [advanced-security]: https://github.com/features/security
 [github-codescanning]: https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning
 [github-secretscanning]: https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning
 [github-supplychain]: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security
-
 [python-setup]: https://github.com/actions/setup-python
 [vendored]: https://github.com/advanced-security/policy-as-code/tree/main/vendor/README.md
 [examples-actions]: https://github.com/advanced-security/policy-as-code/tree/main/examples/workflows
 [examples-cli]: https://github.com/advanced-security/policy-as-code/tree/main/examples/scripts
-
 [permissions]: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs#overview
 [permissions-codescanning]: https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository
 [permissions-secretscanning]: https://docs.github.com/en/rest/secret-scanning/secret-scanning#list-secret-scanning-alerts-for-a-repository