suphm 0.3.0__tar.gz

suphm-0.3.0/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  # Keep GitHub Actions up to date so security patches in the actions
+  # themselves don't sit waiting for a human bump.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "ci"
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Python dependencies in pyproject.toml. Grouped to avoid PR sprawl;
+  # weekly cadence so noise stays manageable.
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "deps"
+    groups:
+      production:
+        dependency-type: production
+      development:
+        dependency-type: development

suphm-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Allow python-publish.yml to reuse this workflow as the pre-publish test gate.
+  workflow_call:
+
+# Cancel in-progress runs when a new push lands on the same branch/PR.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src/ tests/
+
+      - name: Type-check (mypy)
+        run: mypy src/
+
+      - name: Tests (pytest)
+        run: pytest -q

suphm-0.3.0/.github/workflows/python-publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+# Two simultaneous releases would race on the same PyPI version.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pre-publish tests
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: build sdist + wheel
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          # Pinned to a single supported version for reproducible builds.
+          # Bump intentionally; do not use "3.x" (would silently follow
+          # whatever the runner ships and could miss our 3.10 floor).
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      # Trusted Publishing (OIDC) - no PyPI token required in repo secrets.
+      # PyPI side: configure a publisher pointing at SemClone/suphm with
+      # workflow=python-publish.yml and environment=pypi.
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/suphm
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

suphm-0.3.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# suphm-specific
+# Local analysis output (regenerated on demand; not part of the source).
+analysis_results/
+# Local on-disk cache (default ~/.suphm/, but allow per-repo overrides).
+.suphm/
+# MagicMock paths created if a test accidentally treats a MagicMock as a Path.
+MagicMock/
+# Per-PURL output saved during ad-hoc testing.
+*-result.json
+*-analysis.json

suphm-0.3.0/AUTHORS.md

@@ -0,0 +1,9 @@
+# Authors
+
+## Project Lead
+
+* Oscar Valenzuela B. - Project creator and maintainer
+
+---
+
+For a complete list of all contributors, please see the [GitHub contributors page](https://github.com/SemClone/suphm/graphs/contributors).

suphm-0.3.0/CHANGELOG.md

@@ -0,0 +1,295 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.3.0] - 2026-04-29
+
+### Changed (BREAKING)
+
+- **Project renamed** from `ccda-cli` to `suphm` (Supply Chain Health Metrics).
+  The repo also moved from `SemClone/ccda-cli` to `SemClone/suphm`.
+- Python package: `ccda_cli` → `suphm`. All imports change.
+  ```python
+  # before
+  from ccda_cli.metrics.git import GitMetricsAnalyzer
+  # after
+  from suphm.metrics.git import GitMetricsAnalyzer
+  ```
+- CLI entry point: `ccda-cli` → `suphm`. Update any scripts.
+- Distribution name on PyPI: `ccda-cli` → `suphm` (new package; the old one
+  will not be updated further).
+- Cache directory: `~/.ccda/` → `~/.suphm/`. Existing caches are not migrated;
+  delete the old directory or copy contents over manually.
+- Project config file: `./ccda-config.yaml` → `./suphm-config.yaml`.
+- Environment variables:
+  - `CCDA_GITHUB_TOKEN` → `SUPHM_GITHUB_TOKEN`
+  - `CCDA_SERPAPI_KEY` → `SUPHM_SERPAPI_KEY`
+  - `CCDA_CACHE_DIR` → `SUPHM_CACHE_DIR`
+  - `GITHUB_TOKEN` continues to work as a fallback.
+- Repo-clone metadata file in cache: `.ccda-metadata.json` → `.suphm-metadata.json`.
+  Repos cloned by older versions will be re-cloned on first use.
+
+## [0.2.2] - 2026-01-14
+
+### Fixed
+
+- **Critical**: Fixed malformed GitHub URLs with `git+` prefix causing clone failures
+  - Discovery stage now properly normalizes GitHub URLs by stripping `git+` prefix
+  - Removes `.git` suffix and trailing paths (`/issues`, `/pulls`, `/wiki`, etc.)
+  - Replaces `git://` protocol with `https://`
+  - Affects all npm packages and potentially other ecosystems
+  - Missing metrics restored: Bus Factor, Pony Factor, Elephant Factor, Commit Activity, Contributor Retention, License Stability
+  - Now collecting all 10 health metrics instead of only 4 for affected packages
+  - Added `_normalize_github_url()` helper function in `discovery/resolver.py`
+  - Applied normalization to all repository URL assignments across all discovery sources
+
+## [0.2.1] - 2026-01-13
+
+### Fixed
+
+- **Critical**: Fixed pkg:github package analysis failure with 'ecosystem' parameter error
+  - Fixed `_github_discovery_step` in `pipeline.py` passing invalid parameters to `DiscoveryResult`
+  - Removed non-existent `ecosystem` parameter
+  - Changed `github_url` to correct `repository_url` parameter
+  - Removed non-existent `success` parameter
+  - Changed `metadata` to correct `registry_data` parameter
+  - Added required `version` parameter
+  - GitHub packages like `pkg:github/hashicorp/terraform` now analyze successfully
+
+## [0.2.0] - 2026-01-13
+
+### Added
+
+- **Phase 4 Metric A.6: Review Turnaround Time**
+  - New `avg_review_turnaround_hours` metric in pull request data
+  - New `median_review_turnaround_hours` metric in pull request data
+  - Track `prs_with_reviews` and `prs_without_reviews` counts
+  - Samples up to 50 recent PRs to calculate time from PR creation to first review
+  - Handles APPROVED, CHANGES_REQUESTED, and COMMENTED review states
+
+- **Phase 4 Metric A.8: New Contributor Rate**
+  - New `new_contributors_count` metric in time window data (90d, 180d, 365d)
+  - New `new_contributors_per_month` metric showing monthly rate
+  - New `contributor_growth_rate` showing percentage of contributors who are new
+  - Tracks contributors whose first commit falls within each time window
+
+### Changed
+
+- Enhanced `PullRequestMetrics` dataclass with review turnaround fields
+- Added `get_pull_reviews()` method to `GitHubClient` for fetching PR reviews
+- Enhanced `TimeWindowMetrics` dataclass with new contributor rate fields
+
+## [0.1.10] - 2026-01-12
+
+### Fixed
+
+- **Critical**: Fixed golang package GitHub metrics discovery
+  - Fixed `depsdev_ecosystem` property to handle "golang" vs "go" type mismatch
+  - Fixed `_discover_from_depsdev` to support both "go" and "golang" types
+  - Golang packages now correctly infer GitHub URL from package namespace
+  - Example: `pkg:golang/github.com/gin-gonic/gin` now discovers `https://github.com/gin-gonic/gin`
+  - Root cause: packageurl library returns `type="golang"` but code only checked for `"go"`
+
+## [0.1.9] - 2026-01-12
+
+### Changed
+
+- Version bump to publish GitHub PURL support to PyPI
+- No code changes from 0.1.8 (which included the GitHub PURL feature but was not published with it)
+
+## [0.1.8] - 2026-01-12
+
+### Added
+
+- **Native pkg:github/* PURL support** for direct GitHub package analysis
+  - Early PURL detection in `AnalysisPipeline.analyze()` to identify GitHub packages
+  - New `_analyze_github_package()` method for specialized GitHub package analysis
+  - New `_github_discovery_step()` helper for minimal discovery without external API calls
+  - Direct GitHub API access for metrics collection (no tarball download required)
+  - Simplified 3-step pipeline for GitHub packages: Discovery → GitHub Metrics → Health Score
+
+### Changed
+
+- GitHub packages now skip package registry discovery (not needed for pkg:github/*)
+- GitHub packages no longer require tarball download or git cloning
+- Analysis time for GitHub packages reduced from ~80s to ~10s
+
+### Fixed
+
+- Analysis failures for GitHub PURLs like `pkg:github/hashicorp/terraform` and `pkg:github/actions/checkout`
+- Unnecessary package registry lookups for GitHub-native packages
+
+## [0.1.7] - 2026-01-05
+
+### Fixed
+
+- **Critical**: Fixed company affiliation enrichment silently failing
+  - Company enrichment was not working due to async/await execution context issue
+  - `_enrich_contributors()` was calling async code from within an executor thread
+  - Added proper event loop detection and thread-safe async execution
+  - Now correctly handles both standalone and executor-based execution contexts
+  - Company data now properly populates in metrics output
+
+## [0.1.6] - 2026-01-05
+
+### Added
+
+- **Company affiliation enrichment** via GitHub API (optional, requires GitHub token)
+  - Automatically enriches contributor data with company information from GitHub user profiles
+  - Extracts GitHub usernames from commit emails (e.g., `username@users.noreply.github.com`)
+  - Fetches user profiles from GitHub API in batch to minimize API calls
+  - Caches user profiles for 30 days to avoid duplicate requests
+  - Normalizes company names using configurable mappings (e.g., "@google" → "Google")
+  - Respects GitHub API rate limits and degrades gracefully
+  - Falls back to email domain detection when API unavailable or rate limited
+  - Provides more accurate elephant factor and company distribution metrics
+- New `CompanyEnricher` class in `ccda_cli.enrichment.company` module
+- Configuration option `github.enrich_company_affiliation` (default: true when token provided)
+- Comprehensive test suite for company enrichment (16 unit tests)
+- Enhanced documentation in `docs/github-token-setup.md` with company enrichment examples
+
+### Changed
+
+- `GitMetricsAnalyzer` now accepts optional `github_token` parameter for enrichment
+- Company detection now prioritizes GitHub API data over email domain mapping (when token available)
+- Updated README.md to highlight company affiliation enrichment feature
+
+## [0.1.5] - 2026-01-05
+
+### Added
+
+- **osslili as required dependency** for professional license detection
+  - Replaced brittle pattern-matching with osslili's Python API
+  - Accurate SPDX license identification with confidence scores
+  - Copyright statement extraction
+  - Support for all osslili detection methods (metadata, file analysis, keyword matching)
+
+### Fixed
+
+- **Critical**: Cargo package tarball scanning now works correctly
+  - Fixed `.crate` file download from crates.io (was downloading as `download` with no extension)
+  - Added `.crate` extension support to archive extraction
+  - Enhanced download URL detection to handle redirects properly (checks Content-Disposition header and final redirect URL)
+- License file detection now works for all ecosystems
+  - Removed incomplete `LICENSE_PATTERNS` that missed common patterns like `LICENSE-MIT`, `LICENSE-APACHE`
+  - Now uses osslili for comprehensive license file discovery
+- Relative path display in scan results (shows `serde-1.0.228/LICENSE-MIT` instead of full temp paths)
+
+### Changed
+
+- **Breaking**: osslili is now a required dependency (previously optional)
+- **Breaking**: purl2src is now a required dependency (previously optional)
+- Removed optional dependency groups `scanner` and `all`
+- Tarball scanner completely refactored to use osslili Python API
+  - Deleted 200+ lines of brittle pattern-matching code
+  - Removed fallback license detection methods
+  - Scan method now always reports `osslili`
+- Cleaned up unused code and imports from tarball scanner
+
+### Removed
+
+- Removed obsolete methods: `_check_tool`, `_resolve_command`, `_build_command`, `_run_external_tool`, `_run_osslili`, `_run_upmex`, `_apply_osslili_results`, `_apply_upmex_results`, `_analyze_license_file`
+- Removed `LICENSE_PATTERNS` and `COPYRIGHT_PATTERNS` constants
+- Removed support for external tool command-line integration (now uses Python APIs directly)
+
+## [0.1.4] - 2026-01-04
+
+### Added
+
+- **purl2src integration** for automatic download URL discovery
+  - Integrated purl2src library as optional dependency
+  - Tarball scanner now auto-discovers download URLs from PURLs
+  - Fallback to PackageResolver if purl2src unavailable
+  - New optional dependency group: `scanner` and `all`
+- Crates.io (Rust Cargo) package discovery integration
+  - Full metadata extraction from crates.io API
+  - Registry data snapshot including downloads, keywords, and categories
+  - Tarball URL resolution for package scanning
+- Enhanced tarball scanner with external tool integration support
+  - Support for osslili and upmex external scanning tools
+  - Dynamic scan method tracking (builtin, osslili, upmex, or combined)
+  - Improved license detection and binary file analysis
+
+### Fixed
+
+- Test suite compatibility with Python 3.14
+- Virtual environment setup and package installation workflow
+
+## [0.1.3] - 2026-01-04
+
+### Added
+
+- Dynamic API sampling based on GitHub token authentication status
+  - Authenticated (5000 calls/hr): Fetches up to 5000 issues, 5000 PRs, 2000 closed issues
+  - Unauthenticated (60 calls/hr): Conservative limits of 300 items per category
+- Sampling metadata in JSON output for transparency
+  - `_sampling` field in `IssueMetrics` showing sample size vs total count
+  - `_sampling` field in `PullRequestMetrics` with coverage information
+  - Coverage percentage indicator for quality assessment
+
+### Fixed
+
+- **Critical**: Metrics severely underreported due to hard-coded 300-item limit regardless of token
+  - Issue sample size increased from 300 to 5000 when authenticated (16x improvement)
+  - PR sample size increased from 300 to 5000 when authenticated (16x improvement)
+  - Unlabeled rate now calculated from proper sample size
+  - Unresponded rate now reflects larger sample for better accuracy
+- Burnout score `issue_backlog` now uses adjusted full count instead of sampled count
+- PR counts (open/merged/closed) now reflect comprehensive data instead of first 300 items
+
+### Changed
+
+- `IssueMetrics` dataclass now includes `sampled_open_count` and `sampled_closed_count` fields
+- `PullRequestMetrics` dataclass now includes `sampled_count` field
+- GitHub API collector now adapts page limits based on token availability
+
+## [0.1.2] - 2026-01-04
+
+### Fixed
+
+- Use actual `open_issues_count` from GitHub repo API instead of sampled count (max 300)
+- Subtract open PRs from issue count for accurate totals
+- Fixes incorrect burnout score `issue_backlog` calculation
+
+## [0.1.1] - 2026-01-04
+
+### Added
+
+- `chaoss_metrics` field to `HealthScoreResult` containing bus_factor, pony_factor, elephant_factor, and contributor_count
+- `extended_metrics` field to `HealthScoreResult` containing commit_frequency, commits_per_day, pr_velocity, median_pr_merge_hours, branch_protected, and has_signed_releases
+- Helper methods `_classify_frequency()` and `_classify_velocity()` for categorizing activity levels
+
+### Fixed
+
+- Dashboard template compatibility by exposing CHAOSS and extended metrics in health score output (#1)
+
+## [0.1.0] - 2026-01-03
+
+### Initial Release
+
+First public release of ccda-cli - Supply Chain Security Metrics tool.
+
+### Features
+
+- Multi-ecosystem package analysis (npm, PyPI, Cargo, Maven, Go)
+- Health score calculation (0-100) based on commit activity, contributor diversity, and community health
+- Burnout score detection for maintainer sustainability risk assessment
+- CHAOSS metrics computation (bus factor, pony factor, elephant factor)
+- GitHub API integration for community health indicators (stars, forks, issues, PRs)
+- Package tarball scanning for license compliance and binary detection
+- Multiple discovery sources (deps.dev, ecosyste.ms, package registries, SerpAPI fallback)
+- CLI commands: analyze, discover, cache management
+- JSON output format for integration with other tools
+- Comprehensive documentation and usage examples
+
+### Documentation
+
+- Complete README with installation and usage instructions
+- Contribution guidelines (CONTRIBUTING.md)
+- Code of Conduct (CODE_OF_CONDUCT.md)
+- Authors and credits (AUTHORS.md)
+- Detailed documentation for API integrations and configuration
+
+### License
+
+GNU Affero General Public License v3.0