🧤 Gardener

Gardener is a static dependency analysis tool that builds import graphs from any supported project's source code and analyzes them to produce recommendations for distributing OSS funding across that project's external dependencies via Drip Lists.

"If you really want to be a good gardener, you need to understand what is going on in your soil" — Jeff Lowenfels

"Feed the soil, not your plants" — Charles Dowding

⚠️ Status: actively developed. Interfaces may evolve.

What Gardener does

• Scans a project's package manifests and code (Javascript/Typescript, Python, Go, Rust, Solidity) and builds a dependency graph representing the static import relationships of the project's local files, external dependencies, and their components
• Computes and aggregates importance scores (PageRank or Katz) over that graph
• Resolves external dependencies' repository URLs (npm, PyPI, crates.io, Go proxy, Git submodules, GitHub/GitLab/Bitbucket normalization)
• Produces:
  • Recommended Drip Lists with normalized percentages, aggregated per external dependency's canonical repository URL
  • JSON exports with complete node-link graphs
  • Optional interactive graph visualizations
• Runs as a CLI (analyze any local path or remote Git URL) or as a microservice (FastAPI + Celery + Redis + PostgreSQL)

Documentation

For complete documentation including installation, API reference, and deployment guides, see:

• Core analysis modules and CLI (gardener/)
• API, worker, database models (services/)
• Tests (tests/)

Quick start

CLI for local analysis

# Create a virtualenv and install dev+test extras
uv pip install -e '.[dev,test]'
uv pip install -e '.[viz]'  # optional dependency for visualization

# If using Solidity projects with Hardhat TS remappings, install the small Node helper once:
make js-helpers

# Analyze local repository
python -m gardener.main_cli /path/to/repo

# Or a GitHub-, GitLab-, or Bitbucket-hosted repository
python -m gardener.main_cli https://github.com/owner/repo

Options:

• -o, --output PREFIX - Output file prefix (default: ownerName_repoName)
• -v, --verbose - Enable debug logging
• -l, --languages LANGS - Languages to focus the analysis on (comma-separated)
• -c, --config JSON - Configuration overrides
• --visualize - Generate interactive graph visualization (requires '[.viz]' extra)

Outputs:

• In-console results summary
• output/<prefix>_dependency_analysis.json
• output/<prefix>_dependency_graph.html (if '--visualize' is used and '.[viz]' is installed)

Microservice

cp .env.example .env
# Set at minimum:
# POSTGRES_PASSWORD=...
# HMAC_SHARED_SECRET=<32+ characters>

docker-compose up --build

• Submit a job: POST /api/v1/analyses/run with (requires auth and a repo_url in the send data, returns a job_id and repository_id)
  • Run services/scripts/gen_token.py to generate the Bearer token; see the services docs for more details
• Check job status: GET /api/v1/analyses/{job_id}
• Fetch latest results:
  • By repository_id: GET /api/v1/repositories/{repository_id}/results/latest (by repository_id)
  • Or by GitHub URL: GET /api/v1/repositories/results/latest?repository_url=github.com/owner/repo

License

MIT — see LICENSE.