# GraphShift Discovery
GraphShift Discovery is an AI-augmented Java migration analysis tool that helps developers identify deprecated APIs, assess migration complexity, and plan upgrade paths for Java applications. GraphShift uses python, and you will need Python 3.8 or higher for compatibility
## Features
- **Single Repository Analysis**: Analyze individual Java repositories for migration readiness
- **Organization-wide Analysis**: Scan multiple repositories across GitHub organizations
- **Migration Readiness Assessment**: Categorize findings by severity (Critical, Warning, Info)
- **Rich HTML Reports**: Interactive reports with filtering, sorting, and visual indicators
- **Multiple Output Formats**: JSON, HTML, and CSV outputs for different use cases
- **Configurable Scope**: Focus on upgrade blockers or comprehensive deprecation analysis
## Installation
### Via pip (Recommended)
```bash
pip install graphshift-discovery
```
### From Source
```bash
git clone https://github.com/graphshift-dev/discovery
cd discovery
pip install -e .
```
## Quick Start
### First Run - Initialization
On first use, GraphShift will prompt you to set up a working directory:
```bash
graphshift init
# GraphShift needs a working directory.
# Working directory [C:\Users\user\AppData\Local\GraphShift]:
```
This working directory will contain:
- `reports/` - Analysis results and HTML reports
- `templates/` - Customizable HTML report templates
- `logs/` - Application logs
- `clones/` - Temporary repository clones
- `temp/` - Temporary analysis files
- `resources/` - Static assets (logo, etc.)
- `config/` - User editable configuration (GitHub Token)
### Basic Commands
#### Health Check
```bash
graphshift health
```
#### Health Check
```bash
graphshift health
```
Verifies system requirements and configuration.
#### Single Repository Analysis
```bash
# Remote repository
graphshift analyze --repo https://github.com/spring-projects/spring-petclinic
# Local repository
graphshift analyze --local-path /path/to/local/repo
# With specific target JDK
graphshift analyze --repo https://github.com/user/repo --to-version 21
# Focus on upgrade blockers only
graphshift analyze --repo https://github.com/user/repo --scope upgrade-blockers
```
#### Organization Analysis
```bash
# Analyze all public repositories in an organization
graphshift analyze --org spring-projects
# Limit number of repositories
graphshift analyze --org spring-projects --max-repos 5
# Analyze with specific parameters
graphshift analyze --org spring-projects --to-version 17 --scope upgrade-blockers
```
## Command Reference
### Global Options
- `--verbose, -v` - Enable verbose logging
- `--config CONFIG` - Specify custom configuration file
### Analysis Commands
#### `graphshift analyze`
Analyze Java repositories for migration issues.
**Repository Selection:**
- `--repo URL` - Analyze single remote repository
- `--local-path PATH` - Analyze local repository
- `--org ORGANIZATION` - Analyze GitHub organization
- `--local-org PATH` - Analyze local directory containing multiple repos
**Analysis Options:**
- `--to-version VERSION` - Target JDK version (default: 21)
- `--scope SCOPE` - Analysis scope: `all-deprecations` or `upgrade-blockers` (default: all-deprecations)
- `--max-repos N` - Maximum repositories to analyze for organization scans (default: 50)
- `--provider PROVIDER` - SCM provider: `github` (default: github)
**Output Options:**
- `--no-keep-clones` - Delete cloned repositories after analysis
#### `graphshift health`
Check system health and configuration.
#### `graphshift init`
Manually initialize or reconfigure GraphShift.
**Options:**
- `--base-dir PATH` - Specify working directory
## Configuration
GraphShift uses a YAML configuration file that is copied to your working directory during initialization. You can customize settings like GitHub tokens, memory allocation, and analysis parameters.
### Managing Configuration
Use the `graphshift config` commands to manage your configuration:
```bash
# Edit configuration (opens in default editor)
graphshift config edit
# View current configuration
graphshift config show
# Show config file location
graphshift config path
```
### GitHub Access
For organization analysis, configure GitHub access:
```yaml
graphshift:
scm:
github:
base_url: "https://api.github.com"
# Add personal access token for private repos or higher rate limits
# token: "your-github-token"
```
**Actions:**
- `graphshift config edit` - Open config file in default editor
- `graphshift config show` - Display current configuration
- `graphshift config path` - Show config file location
## Understanding the Output
### Migration Readiness Status
- **READY** - No blocking issues found
- **READY WITH TECH DEBT** - Minor warnings that should be reviewed
- **BLOCKED** - Critical issues that prevent migration
### Severity Levels
- **Critical** - APIs removed in target JDK version, will cause compilation failures
- **Warning** - APIs deprecated in target JDK version, may be removed in future versions
- **Info** - General deprecation notices for awareness
### Report Files
For each analysis, GraphShift generates:
1. **JSON Report** (`*_analysis.json`) - Raw analysis data for programmatic use
2. **HTML Report** (`*_analysis.html`) - Interactive web report with filtering and sorting
3. **CSV Report** (`*_analysis.csv`) - Tabular data for spreadsheet analysis
### Organization Reports
Organization analysis creates:
- Individual repository reports in subdirectories
- Organization summary report (`*_organization_summary.html`)
- Aggregated JSON data with cross-repository insights
### Analysis Settings
```yaml
graphshift:
jar:
memory: "4g"
initial_memory: "1g"
stack_size: "8m"
```
## Examples
### Analyzing Spring Framework
```bash
graphshift analyze --repo https://github.com/spring-projects/spring-framework --to-version 21
```
### Organization Survey
```bash
graphshift analyze --org apache --max-repos 10 --scope upgrade-blockers
```
### Local Development
```bash
graphshift analyze --local-path ./my-java-project --to-version 17
```
## Architecture
GraphShift Discovery uses a hybrid architecture:
1. **Java Analysis Engine** - Performs AST parsing and deprecation detection
2. **Python Orchestration** - Handles workflow, SCM integration, and report generation
3. **Knowledge Base** - Curated deprecation and removal information
4. **Template System** - Customizable HTML report generation
## System Requirements
- **Python**: 3.8 or higher
- **Java**: JDK 8 or higher (for analysis engine)
- **Memory**: 4GB RAM recommended for large codebases
- **Storage**: Temporary space for repository clones
## Troubleshooting
### Common Issues
**"JAR analyzer not found"**
- Ensure Java is installed and accessible
- Check that the analysis engine was properly packaged
**"No SCM providers configured"**
- Verify GitHub configuration for organization analysis
- Check network connectivity for remote repositories
**"Analysis failed with memory error"**
- Increase JVM memory settings in configuration
- Analyze smaller repository subsets
### Debug Mode
Enable verbose logging for detailed troubleshooting:
```bash
graphshift --verbose analyze --repo https://github.com/user/repo
```
## Contributing
GraphShift Discovery is designed for extensibility:
- **Templates**: Customize HTML reports by modifying templates in your working directory
- **Configuration**: Extend analysis parameters through YAML configuration
- **Integration**: Use JSON output for integration with other tools
## License
Apache License 2.0
## Support
Bugs or Enhancements? https://github.com/graphshift-dev/discovery/issues
Feedback? Send an email to hi@graphshift.dev with subject line Feedback
Raw data
{
"_id": null,
"home_page": "https://github.com/graphshift-dev/discovery",
"name": "graphshift-discovery",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "java migration refactoring analysis ast deprecation",
"author": "GraphShift Team",
"author_email": "contact@graphshift.dev",
"download_url": "https://files.pythonhosted.org/packages/28/d6/093388c9462e363001195e18fecb43bf2e6359539359fb4ba10cc673293e/graphshift_discovery-1.0.0.tar.gz",
"platform": null,
"description": "# GraphShift Discovery\r\n\r\nGraphShift Discovery is an AI-augmented Java migration analysis tool that helps developers identify deprecated APIs, assess migration complexity, and plan upgrade paths for Java applications. GraphShift uses python, and you will need Python 3.8 or higher for compatibility\r\n\r\n## Features\r\n\r\n- **Single Repository Analysis**: Analyze individual Java repositories for migration readiness\r\n- **Organization-wide Analysis**: Scan multiple repositories across GitHub organizations\r\n- **Migration Readiness Assessment**: Categorize findings by severity (Critical, Warning, Info)\r\n- **Rich HTML Reports**: Interactive reports with filtering, sorting, and visual indicators\r\n- **Multiple Output Formats**: JSON, HTML, and CSV outputs for different use cases\r\n- **Configurable Scope**: Focus on upgrade blockers or comprehensive deprecation analysis\r\n\r\n## Installation\r\n\r\n### Via pip (Recommended)\r\n\r\n```bash\r\npip install graphshift-discovery\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/graphshift-dev/discovery\r\ncd discovery\r\npip install -e .\r\n```\r\n\r\n## Quick Start\r\n\r\n### First Run - Initialization\r\n\r\nOn first use, GraphShift will prompt you to set up a working directory:\r\n\r\n```bash\r\ngraphshift init\r\n# GraphShift needs a working directory.\r\n# Working directory [C:\\Users\\user\\AppData\\Local\\GraphShift]: \r\n```\r\n\r\nThis working directory will contain:\r\n- `reports/` - Analysis results and HTML reports\r\n- `templates/` - Customizable HTML report templates\r\n- `logs/` - Application logs\r\n- `clones/` - Temporary repository clones\r\n- `temp/` - Temporary analysis files\r\n- `resources/` - Static assets (logo, etc.)\r\n- `config/` - User editable configuration (GitHub Token)\r\n\r\n### Basic Commands\r\n\r\n#### Health Check\r\n```bash\r\ngraphshift health\r\n```\r\n\r\n#### Health Check\r\n```bash\r\ngraphshift health\r\n```\r\nVerifies system requirements and configuration.\r\n\r\n#### Single Repository Analysis\r\n```bash\r\n# Remote repository\r\ngraphshift analyze --repo https://github.com/spring-projects/spring-petclinic\r\n\r\n# Local repository\r\ngraphshift analyze --local-path /path/to/local/repo\r\n\r\n# With specific target JDK\r\ngraphshift analyze --repo https://github.com/user/repo --to-version 21\r\n\r\n# Focus on upgrade blockers only\r\ngraphshift analyze --repo https://github.com/user/repo --scope upgrade-blockers\r\n```\r\n\r\n#### Organization Analysis\r\n```bash\r\n# Analyze all public repositories in an organization\r\ngraphshift analyze --org spring-projects\r\n\r\n# Limit number of repositories\r\ngraphshift analyze --org spring-projects --max-repos 5\r\n\r\n# Analyze with specific parameters\r\ngraphshift analyze --org spring-projects --to-version 17 --scope upgrade-blockers\r\n```\r\n\r\n## Command Reference\r\n\r\n### Global Options\r\n- `--verbose, -v` - Enable verbose logging\r\n- `--config CONFIG` - Specify custom configuration file\r\n\r\n### Analysis Commands\r\n\r\n#### `graphshift analyze`\r\nAnalyze Java repositories for migration issues.\r\n\r\n**Repository Selection:**\r\n- `--repo URL` - Analyze single remote repository\r\n- `--local-path PATH` - Analyze local repository\r\n- `--org ORGANIZATION` - Analyze GitHub organization\r\n- `--local-org PATH` - Analyze local directory containing multiple repos\r\n\r\n**Analysis Options:**\r\n- `--to-version VERSION` - Target JDK version (default: 21)\r\n- `--scope SCOPE` - Analysis scope: `all-deprecations` or `upgrade-blockers` (default: all-deprecations)\r\n- `--max-repos N` - Maximum repositories to analyze for organization scans (default: 50)\r\n- `--provider PROVIDER` - SCM provider: `github` (default: github)\r\n\r\n**Output Options:**\r\n- `--no-keep-clones` - Delete cloned repositories after analysis\r\n\r\n#### `graphshift health`\r\nCheck system health and configuration.\r\n\r\n#### `graphshift init`\r\nManually initialize or reconfigure GraphShift.\r\n\r\n**Options:**\r\n- `--base-dir PATH` - Specify working directory\r\n\r\n## Configuration\r\n\r\nGraphShift uses a YAML configuration file that is copied to your working directory during initialization. You can customize settings like GitHub tokens, memory allocation, and analysis parameters.\r\n\r\n### Managing Configuration\r\n\r\nUse the `graphshift config` commands to manage your configuration:\r\n\r\n```bash\r\n# Edit configuration (opens in default editor)\r\ngraphshift config edit\r\n\r\n# View current configuration \r\ngraphshift config show\r\n\r\n# Show config file location\r\ngraphshift config path\r\n```\r\n\r\n### GitHub Access\r\n\r\nFor organization analysis, configure GitHub access:\r\n\r\n```yaml\r\ngraphshift:\r\n scm:\r\n github:\r\n base_url: \"https://api.github.com\"\r\n # Add personal access token for private repos or higher rate limits\r\n # token: \"your-github-token\"\r\n```\r\n\r\n**Actions:**\r\n- `graphshift config edit` - Open config file in default editor\r\n- `graphshift config show` - Display current configuration\r\n- `graphshift config path` - Show config file location\r\n\r\n## Understanding the Output\r\n\r\n### Migration Readiness Status\r\n\r\n- **READY** - No blocking issues found\r\n- **READY WITH TECH DEBT** - Minor warnings that should be reviewed\r\n- **BLOCKED** - Critical issues that prevent migration\r\n\r\n### Severity Levels\r\n\r\n- **Critical** - APIs removed in target JDK version, will cause compilation failures\r\n- **Warning** - APIs deprecated in target JDK version, may be removed in future versions\r\n- **Info** - General deprecation notices for awareness\r\n\r\n### Report Files\r\n\r\nFor each analysis, GraphShift generates:\r\n\r\n1. **JSON Report** (`*_analysis.json`) - Raw analysis data for programmatic use\r\n2. **HTML Report** (`*_analysis.html`) - Interactive web report with filtering and sorting\r\n3. **CSV Report** (`*_analysis.csv`) - Tabular data for spreadsheet analysis\r\n\r\n### Organization Reports\r\n\r\nOrganization analysis creates:\r\n- Individual repository reports in subdirectories\r\n- Organization summary report (`*_organization_summary.html`)\r\n- Aggregated JSON data with cross-repository insights\r\n\r\n\r\n\r\n### Analysis Settings\r\n\r\n```yaml\r\ngraphshift:\r\n jar:\r\n memory: \"4g\"\r\n initial_memory: \"1g\"\r\n stack_size: \"8m\"\r\n```\r\n\r\n## Examples\r\n\r\n### Analyzing Spring Framework\r\n```bash\r\ngraphshift analyze --repo https://github.com/spring-projects/spring-framework --to-version 21\r\n```\r\n\r\n### Organization Survey\r\n```bash\r\ngraphshift analyze --org apache --max-repos 10 --scope upgrade-blockers\r\n```\r\n\r\n### Local Development\r\n```bash\r\ngraphshift analyze --local-path ./my-java-project --to-version 17\r\n```\r\n\r\n## Architecture\r\n\r\nGraphShift Discovery uses a hybrid architecture:\r\n\r\n1. **Java Analysis Engine** - Performs AST parsing and deprecation detection\r\n2. **Python Orchestration** - Handles workflow, SCM integration, and report generation\r\n3. **Knowledge Base** - Curated deprecation and removal information\r\n4. **Template System** - Customizable HTML report generation\r\n\r\n## System Requirements\r\n\r\n- **Python**: 3.8 or higher\r\n- **Java**: JDK 8 or higher (for analysis engine)\r\n- **Memory**: 4GB RAM recommended for large codebases\r\n- **Storage**: Temporary space for repository clones\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**\"JAR analyzer not found\"**\r\n- Ensure Java is installed and accessible\r\n- Check that the analysis engine was properly packaged\r\n\r\n**\"No SCM providers configured\"**\r\n- Verify GitHub configuration for organization analysis\r\n- Check network connectivity for remote repositories\r\n\r\n**\"Analysis failed with memory error\"**\r\n- Increase JVM memory settings in configuration\r\n- Analyze smaller repository subsets\r\n\r\n### Debug Mode\r\n\r\nEnable verbose logging for detailed troubleshooting:\r\n```bash\r\ngraphshift --verbose analyze --repo https://github.com/user/repo\r\n```\r\n\r\n## Contributing\r\n\r\nGraphShift Discovery is designed for extensibility:\r\n\r\n- **Templates**: Customize HTML reports by modifying templates in your working directory\r\n- **Configuration**: Extend analysis parameters through YAML configuration\r\n- **Integration**: Use JSON output for integration with other tools\r\n\r\n## License\r\n\r\nApache License 2.0\r\n\r\n## Support\r\n\r\nBugs or Enhancements? https://github.com/graphshift-dev/discovery/issues\r\nFeedback? Send an email to hi@graphshift.dev with subject line Feedback\r\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-Augmented Java Migration Assistant - Open Source Edition",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/graphshift-dev/discovery/issues",
"Documentation": "https://docs.graphshift.dev",
"Homepage": "https://github.com/graphshift-dev/discovery",
"Source": "https://github.com/graphshift-dev/discovery"
},
"split_keywords": [
"java",
"migration",
"refactoring",
"analysis",
"ast",
"deprecation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "13f5d43638b59646bb254a47242a5deb1043f44123150830955af0e8af36ebf0",
"md5": "61656367c89093645ebaaf53289ec6f5",
"sha256": "0a2346e84606f110536d59418ef71affb4c32958c29c06acf5177a2f8b3c7578"
},
"downloads": -1,
"filename": "graphshift_discovery-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61656367c89093645ebaaf53289ec6f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9959505,
"upload_time": "2025-08-03T22:56:14",
"upload_time_iso_8601": "2025-08-03T22:56:14.589171Z",
"url": "https://files.pythonhosted.org/packages/13/f5/d43638b59646bb254a47242a5deb1043f44123150830955af0e8af36ebf0/graphshift_discovery-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "28d6093388c9462e363001195e18fecb43bf2e6359539359fb4ba10cc673293e",
"md5": "67302bf2546632ad29fb7300fd968b08",
"sha256": "f21f8ba5de3871dc5396d1eb8252927df0fc7e8e229566f1d3550ed6bb1fe294"
},
"downloads": -1,
"filename": "graphshift_discovery-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "67302bf2546632ad29fb7300fd968b08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9952106,
"upload_time": "2025-08-03T22:56:24",
"upload_time_iso_8601": "2025-08-03T22:56:24.859145Z",
"url": "https://files.pythonhosted.org/packages/28/d6/093388c9462e363001195e18fecb43bf2e6359539359fb4ba10cc673293e/graphshift_discovery-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 22:56:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "graphshift-dev",
"github_project": "discovery",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
}
],
"lcname": "graphshift-discovery"
}
JSON
