Skip to content

README.md

Latest commit

 

History

History
156 lines (122 loc) · 4.38 KB

README.md

File metadata and controls

156 lines (122 loc) · 4.38 KB

Example Plugin Implementations

This directory contains example plugin implementations for various programming languages that are not yet fully supported in PermitCheck.

Available Examples

1. Ruby Plugin (for_ruby.py)

  • Status: ~80% complete, needs testing
  • Features:
    • Parses Gemfile for dependencies
    • Fetches licenses from RubyGems.org API
    • Fallback to gem specification command
  • Usage: Copy to permitcheck/plugins/ and test with a Ruby project

2. Go Plugin (for_go.py)

  • Status: ~70% complete, needs additional work
  • Features:
    • Parses go.mod for module dependencies
    • GitHub API integration for GitHub-hosted modules
    • LICENSE file detection in module cache
  • Challenges: No unified Go package registry API, requires multiple strategies

3. Java Plugin (for_java.py)

  • Status: ~75% complete for Maven, Gradle stubbed out
  • Features:
    • Parses Maven pom.xml files
    • Fetches licenses from Maven Central
    • Downloads and parses artifact POM files
  • TODO: Gradle support (build.gradle parsing)

How to Use These Examples

Testing an Example Plugin

  1. Copy to plugins directory:
cp examples/for_ruby.py permitcheck/plugins/
  1. Update CLI tool to include new language in permitcheck/scripts/permitcheck_tool.py:
parser.add_argument(
    '-l', '--lang',
    choices=['python', 'npm', 'ruby'],  # Add your language
    # ...
)
  1. Test with sample project:
# Create test project
mkdir test_ruby_project
cd test_ruby_project

# Create Gemfile
cat > Gemfile << EOF
source 'https://rubygems.org'
gem 'rails'
gem 'rspec'
EOF

# Run PermitCheck
permitcheck -l ruby

Customizing for Your Needs

Each plugin can be customized by modifying:

  1. Dependency Discovery: Update _discover_*() method to parse your manifest format
  2. License Fetching: Update _fetch_license_from_*() to query your package registry
  3. Configuration: Implement load_settings() for language-specific config

Implementation Checklist

When adapting these examples:

  • Test dependency discovery with real projects
  • Verify license fetching works for common packages
  • Add error handling for edge cases
  • Write unit tests (see tests/plugins/test_for_python.py)
  • Add integration tests
  • Update documentation
  • Submit PR with your enhancements!

Package Registry APIs

Here are the official APIs for major package registries:

Language Registry API Documentation
Ruby RubyGems https://guides.rubygems.org/rubygems-org-api/
Go pkg.go.dev No official API (use GitHub API for GitHub repos)
Java Maven Central https://search.maven.org/classic/#api
Rust crates.io https://crates.io/data-access
PHP Packagist https://packagist.org/apidoc
C# NuGet https://docs.microsoft.com/nuget/api/overview

Common Patterns

Pattern 1: API Query

Most registries provide JSON APIs:

response = requests.get(f"{API_URL}/{package_name}")
data = response.json()
license = data.get('license')

Pattern 2: CLI Tool Integration

Use existing package manager tools:

result = subprocess.run(['gem', 'specification', package], 
                       capture_output=True)
# Parse result.stdout

Pattern 3: LICENSE File Parsing

Read LICENSE files from installed packages:

license_files = glob.glob(f"{package_dir}/LICENSE*")
content = open(license_files[0]).read()
licenses = self.matcher.match(content)  # Use fuzzy matching

Contributing Your Plugin

Once your plugin works well:

  1. Polish the code:

    • Add comprehensive docstrings
    • Handle edge cases
    • Add type hints
    • Follow code style (run ruff format)

  2. Write tests:

    • Unit tests for each method
    • Mock external API calls
    • Test error conditions

  3. Update docs:

    • Add to README.md supported languages
    • Document any special requirements
    • Add usage examples

  4. Submit PR:

    • Follow CONTRIBUTING.md
    • Include test results
    • Describe what works and what doesn't

Questions?

Happy plugin development! 🚀