OSS Sustain Guard: A Multi‑Ecosystem Sustainability Analyzer for Enterprise Open‑Source Dependency Management

## Overview OSS Sustain Guard fills a critical gap for organizations that rely on dozens or hundreds of open‑source components. By aggregating metrics such as maintainer activity, contributor health, security posture, and funding signals, the tool translates raw repository data into an actionable snapshot that guides procurement and stewardship decisions. The core concept is simple: *awareness first*. When a high‑profile incident surfaces, a team can inspect a single report to understand the risk surface of every transitive dependency instead of hunting through GitHub issue lists. OSS Sustain Guard is engineered to give that awareness at scale, across all major ecosystems. ## Philosophy and Approach ### Empathetic, Context‑Sensitive Evaluation The project eschews blame‑culture in favor of constructive language. Sustainability is acknowledged as a spectrum that varies between corporate‑backed and community‑driven projects. Consequently, the scoring system distinguishes between these models, letting users choose a *balanced*, *security‑first*, *contributor‑experience*, or *long‑term‑stability* profile. ### Metrics as One Lens Metrics are grounded in the CHAOSS standards, providing a solid research foundation: - **Contributor Health** – Number and distribution of active contributors. - **Development Activity** – Commit cadence, issue resolution speed. - **Community Engagement** – PR reviews, discussion threads. - **Project Maturity** – Release frequency, version life‑cycle. - **Security** – Vulnerability disclosures and patch timelines. Each core metric is scored on a 0‑10 scale, and the tool aggregates these into a composite score that is transparently broken down. ## Core Features | Feature | Description | |---------|-------------| | **24 Sustainability Metrics** | Covers maintainers, contributors, community, maturity, and security, all scored 0‑10. | | **Trend Analysis** | Historical view of scores across multiple windows, enabling proactive risk mitigation. | | **CHAOSS Alignment** | Five models (Stability, Sustainability, Community Engagement, Project Maturity, Contributor Experience) for flexible evaluation. | | **Multi‑Ecosystem Support** | Out‑of‑the‑box analysis for Python, JavaScript, Go, Rust, PHP, Java, Kotlin, C#, Ruby, and more. | | **Repository‑Level Scoring** | Provides local caching to reduce API calls, GitHub tokens cover most repos, GitLab tokens required only for gitlab.com. | | **Extensibility** | Pluggable architecture lets teams add new metrics, resolvers, or VCS providers. | | **CI/CD Integration** | Native hooks for GitHub Actions, pre‑commit, and generic CI pipelines. | | **Funding Awareness** | Displays funding links for community projects and a *Gratitude Vending Machine* to surface those most in need of support. | ## Developer Workflow 1. **Manifest Detection** – The tool auto‑detects `requirements.txt`, `package.json`, `Cargo.toml`, and more, even within monorepos. 2. **Recursive Scanning** – Traverses directories, respecting an `exclude` configuration for internal or legacy dependencies. 3. **Analysis** – Connects to GitHub/GitLab (via OAuth tokens) or reads locally cached snapshots. Results are cached to speed up subsequent runs. 4. **Output** – Generates a detailed report with metric break‑downs, trend charts, and actionable suggestions. The report can be consumed in CI or displayed on a dashboard. 5. **Plugging in** – Teams can write custom plugins for new package ecosystems, VCS integrations, or bespoke scoring logic. ## Installation & Quick Start ```bash pip install oss-sustain-guard ``` A minimal invocation: ```bash sustain-guard analyze ./my-project ``` For CI integration, add a step in GitHub Actions: ```yaml - name: Run OSS Sustain Guard uses: myorg/oss-sustain-guard-action@v1 with: token: ${{ secrets.GITHUB_TOKEN }} ``` ## Extensibility & Customization - **Custom Resolvers** – Add new package manifests via plugin modules. - **Custom VCS Providers** – Extend analysis to other version‑control platforms. - **Custom Scoring Profiles** – Define integer weights per metric and normalize to a 0‑100 scale, enabling tailoring to an organization’s risk appetite. The tool’s plugin system lives in the `oss_sustain_guard.plugins` package, making it straightforward for experienced developers to contribute new logic. ## Community & Support OSS Sustain Guard is open source under the MIT License. The maintainer community actively welcomes contributions, especially in the form of new metric definitions and ecosystem plugins. Frequently Asked Questions and troubleshooting guides are available in the documentation hub. ## Conclusion For teams that need to audit their open‑source footprint accurately, OSS Sustain Guard delivers a comprehensive, metrics‑driven view while maintaining a respectful, collaboration‑oriented user experience. Its cross‑language coverage, transparent scoring, and built‑in CI friendliness make it a valuable addition to any DevOps pipeline focused on sustainable software supply chains.