{"id":31250584,"url":"https://github.com/sshaaf/waver","last_synced_at":"2025-09-23T05:32:28.777Z","repository":{"id":306284697,"uuid":"1024423606","full_name":"sshaaf/waver","owner":"sshaaf","description":"An easy to use code tutorial generator","archived":false,"fork":false,"pushed_at":"2025-09-18T11:44:35.000Z","size":234,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-18T13:42:15.226Z","etag":null,"topics":["generator","java","tutorial"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sshaaf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-22T17:13:47.000Z","updated_at":"2025-09-18T11:44:38.000Z","dependencies_parsed_at":"2025-07-24T20:56:16.503Z","dependency_job_id":"3cc07b13-5728-46c8-8ae3-ac180fe10c77","html_url":"https://github.com/sshaaf/waver","commit_stats":null,"previous_names":["sshaaf/waver"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sshaaf/waver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Fwaver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Fwaver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Fwaver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Fwaver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshaaf","download_url":"https://codeload.github.com/sshaaf/waver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaaf%2Fwaver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276519130,"owners_count":25656556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generator","java","tutorial"],"created_at":"2025-09-23T05:32:27.537Z","updated_at":"2025-09-23T05:32:28.762Z","avatar_url":"https://github.com/sshaaf.png","language":"Java","readme":"\u003c!-- For a centered logo --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/waver-128.png\" alt=\"Project Logo\" width=\"128\"\u003e\n\u003c/p\u003e\n\u003ch2 align=\"center\"\u003e\n  \u003cb\u003e Waver - An easy to use code tutorial generator \u003c/b\u003e\n\u003c/h2\u003e\n\nWaver is a command-line tool that generates code tutorials from source code using Large Language Models (LLMs). It analyzes the source code, identifies abstractions and relationships, and generates a structured tutorial with chapters.\n\n\n\u003e **AI-Powered Code Documentation Engine** - Transform your codebase into comprehensive technical tutorials using state-of-the-art Large Language Models\n\n[![Java 21+](https://img.shields.io/badge/Java-21+-orange.svg)](https://openjdk.org/projects/jdk/21/)\n[![LangChain4j](https://img.shields.io/badge/LangChain4j-1.0.0-blue.svg)](https://docs.langchain4j.dev/)\n[![Native Image](https://img.shields.io/badge/GraalVM-Native-green.svg)](https://www.graalvm.org/latest/reference-manual/native-image/)\n[![Maven Central](https://img.shields.io/badge/Maven-Central-red.svg)](https://central.sonatype.com/)\n\n## 🚀 What is Waver?\n\nWaver is a sophisticated **code analysis and documentation generation tool** that leverages advanced AI models to automatically create in-depth technical tutorials from your source code. Built on a **robust pipeline architecture**, it combines static code analysis with intelligent LLM processing to produce documentation that actually understands your software's architecture.\n\n### 🔥 Technical Highlights\n\n- **🧠 Multi-Stage AI Pipeline**: 6-stage processing pipeline with specialized tasks\n- **⚡ Native Binary Support**: GraalVM native compilation for lightning-fast execution  \n- **🎯 Smart Code Analysis**: Deep abstraction and relationship detection\n- **🔌 Pluggable LLM Providers**: OpenAI GPT models and Google Gemini support\n- **📊 Multiple Output Formats**: Markdown, HTML, and PDF generation\n- **🏗️ Production-Ready**: Built with enterprise patterns and error handling\n\n## 🏛️ Architecture Overview\n\n```\nSource Code → Pipeline → Generated Tutorial\n     ↓\n┌─────────────────────────────────────────────────────┐\n│  📂 CodeCrawlerTask        │  Filesystem analysis   │\n│  🔍 IdentifyAbstractionsTask │  Pattern recognition │  \n│  🔗 IdentifyRelationshipsTask│  Dependency mapping  │\n│  📚 ChapterOrganizerTask    │  Content structuring  │\n│  ✍️  TechnicalWriterTask    │  AI content generation│\n│  📝 MetaInfoTask           │  Metadata \u0026 navigation │\n└─────────────────────────────────────────────────────┘\n```\n\n## ⚡ Quick Start\n\n### Prerequisites\n\n- **Java 21+** (LTS recommended)\n- **Maven 3.9+** \n- **API Key** for your chosen LLM provider\n\n### Installation \u0026 Build\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo-url\u003e\ncd waver\n\n# Build executable JAR\nmvn clean package\n\n# Or build native binary for optimal performance\nmvn clean package -Pnative\n```\n\n### Environment Setup\n\n```bash\n# For OpenAI (recommended for complex codebases)\nexport OPENAI_API_KEY=\"sk-your-openai-api-key-here\"\n\n# For Google Gemini (recommended for cost optimization)\nexport GEMINI_AI_KEY=\"your-gemini-api-key-here\"\n```\n\n## 🔧 Command Reference\n\n### Basic Syntax\n```bash\njava -jar target/waver-cli-0.1.0.jar [OPTIONS]\n# or with native binary:\n./target/waver-cli [OPTIONS]\n```\n\n### Required Parameters\n\n| Parameter | Short | Description | Example |\n|-----------|-------|-------------|---------|\n| `--input` | - | Source code directory | `--input ./src/main/java` |\n| `--output` | - | Output directory | `--output ./docs` |\n| `--type` | `-t` | Generation type | `--type tutorial` |\n| `--llm-provider` | - | AI model provider | `--llm-provider OpenAI` |\n\n### Optional Parameters\n\n| Parameter | Short | Description | Default | Example |\n|-----------|-------|-------------|---------|---------|\n| `--verbose` | `-v` | Debug logging | `false` | `-v` |\n| `--format` | - | Output format | `MARKDOWN` | `--format PDF` |\n| `--help` | `-h` | Show help | - | `-h` |\n| `--version` | - | Show version | - | `--version` |\n\n### Generation Types\n- `tutorial` ✅ **Available**: Comprehensive code tutorials\n- `documentation` ⏳ **Coming Soon**: API documentation\n- `blog` ⏳ **Coming Soon**: Blog post generation\n\n### LLM Providers\n- `OpenAI` ✅ **GPT-3.5/4**: Best for complex analysis\n- `Gemini` ✅ **Google AI**: Cost-effective option\n\n### Output Formats  \n- `MARKDOWN` ✅ **Default**: GitHub/GitLab ready\n- `HTML` ✅ **Web**: Styled documentation\n- `PDF` ✅ **Print**: Professional reports\n\n## 💻 Usage Examples\n\n### 1. Basic Tutorial Generation\n```bash\njava -jar target/waver-cli-0.1.0.jar \\\n  --input ./src/main/java \\\n  --output ./tutorials \\\n  --type tutorial \\\n  --llm-provider OpenAI\n```\n\n### 2. Spring Boot Project with Verbose Logging\n```bash\njava -jar target/waver-cli-0.1.0.jar \\\n  --input ./spring-boot-app/src \\\n  --output ./documentation \\\n  --type tutorial \\\n  --llm-provider Gemini \\\n  --verbose\n```\n\n### 3. Generate PDF Documentation\n```bash\njava -jar target/waver-cli-0.1.0.jar \\\n  --input ./microservice \\\n  --output ./reports \\\n  --type tutorial \\\n  --llm-provider OpenAI \\\n  --format PDF\n```\n\n### 4. Native Binary Execution (Faster)\n```bash\n./target/waver-cli \\\n  --input ./complex-system/backend \\\n  --output ./technical-docs \\\n  --type tutorial \\\n  --llm-provider Gemini \\\n  --format HTML \\\n  --verbose\n```\n\n### 5. Multi-Module Maven Project\n```bash\njava -jar target/waver-cli-0.1.0.jar \\\n  --input ./enterprise-app \\\n  --output ./team-docs \\\n  --type tutorial \\\n  --llm-provider OpenAI \\\n  --verbose\n```\n\n## 🔄 CI/CD Integration\n\n### GitHub Actions Workflow\n\n```yaml\nname: 📚 Auto-Generate Documentation\non:\n  push:\n    branches: [main, develop]\n    paths: ['src/**', 'pom.xml']\n  pull_request:\n    branches: [main]\n\njobs:\n  generate-docs:\n    runs-on: ubuntu-latest\n    \n    steps:\n    - name: 🚀 Checkout Code\n      uses: actions/checkout@v4\n      \n    - name: ☕ Setup Java 21\n      uses: actions/setup-java@v4\n      with:\n        java-version: '21'\n        distribution: 'temurin'\n        cache: 'maven'\n        \n    - name: 🔨 Build Waver Native Binary\n      run: |\n        mvn clean package -Pnative -DskipTests\n        \n    - name: 📖 Generate Technical Documentation\n      run: |\n        ./target/waver-cli \\\n          --input ./src \\\n          --output ./generated-docs \\\n          --type tutorial \\\n          --llm-provider OpenAI \\\n          --format MARKDOWN \\\n          --verbose\n      env:\n        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n        \n    - name: 📤 Deploy to GitHub Pages\n      uses: peaceiris/actions-gh-pages@v3\n      if: github.ref == 'refs/heads/main'\n      with:\n        github_token: ${{ secrets.GITHUB_TOKEN }}\n        publish_dir: ./generated-docs\n        \n    - name: 💬 Comment on PR\n      if: github.event_name == 'pull_request'\n      uses: actions/github-script@v7\n      with:\n        script: |\n          github.rest.issues.createComment({\n            issue_number: context.issue.number,\n            owner: context.repo.owner,\n            repo: context.repo.repo,\n            body: '📚 Documentation has been generated! Check the artifacts below.'\n          })\n```\n\n### GitLab CI Pipeline\n\n```yaml\nstages:\n  - build\n  - document\n  - deploy\n\nvariables:\n  MAVEN_OPTS: \"-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository\"\n\ncache:\n  paths:\n    - .m2/repository/\n\nbuild-waver:\n  stage: build\n  image: bellsoft/liberica-openjdk-alpine:21\n  script:\n    - mvn clean package -Pnative -DskipTests\n  artifacts:\n    paths:\n      - target/waver-cli\n    expire_in: 1 hour\n\ngenerate-docs:\n  stage: document\n  image: bellsoft/liberica-openjdk-alpine:21\n  dependencies:\n    - build-waver\n  script:\n    - chmod +x target/waver-cli\n    - ./target/waver-cli \n        --input ./src \n        --output ./documentation \n        --type tutorial \n        --llm-provider OpenAI \n        --format HTML\n        --verbose\n  artifacts:\n    paths:\n      - documentation/\n    expire_in: 1 week\n  only:\n    - main\n    - develop\n```\n\n### Docker Integration\n\n```dockerfile\n# Multi-stage build for minimal container size\nFROM bellsoft/liberica-openjdk-alpine:21 AS builder\nWORKDIR /app\nCOPY pom.xml .\nCOPY src ./src\nRUN mvn clean package -Pnative -DskipTests\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nCOPY --from=builder /app/target/waver-cli /usr/local/bin/waver\nENTRYPOINT [\"waver\"]\n```\n\n```bash\n# Build and run in container\ndocker build -t waver-cli .\ndocker run --rm \\\n  -v $(pwd)/src:/input \\\n  -v $(pwd)/docs:/output \\\n  -e OPENAI_API_KEY=\"$OPENAI_API_KEY\" \\\n  waver-cli \\\n  --input /input \\\n  --output /output \\\n  --type tutorial \\\n  --llm-provider OpenAI\n```\n\n## ⚙️ Advanced Configuration\n\n### Performance Tuning\n\n```bash\n# JVM tuning for large codebases\nexport JAVA_OPTS=\"-Xmx4g -XX:+UseG1GC -XX:G1HeapRegionSize=16m\"\n\njava $JAVA_OPTS -jar target/waver-cli-0.1.0.jar \\\n  --input ./large-enterprise-app \\\n  --output ./comprehensive-docs \\\n  --type tutorial \\\n  --llm-provider OpenAI \\\n  --verbose\n```\n\n### Native Image Configuration\n\nThe project includes optimized GraalVM native-image configuration:\n\n- **Reflection Config**: Pre-configured for LangChain4j and internal components\n- **Proxy Config**: Dynamic proxy support for AI service interfaces  \n- **Resource Config**: Bundled prompt templates and configuration files\n- **Build Args**: Optimized initialization and security settings\n\n```bash\n# Custom native build with additional options\nmvn clean package -Pnative \\\n  -Dquarkus.native.additional-build-args=\"-H:+ReportExceptionStackTraces,-H:+PrintClassInitialization\"\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**🚨 \"Environment variable not set\" Error**\n```bash\n# Verify API key is set\necho $OPENAI_API_KEY\necho $GEMINI_AI_KEY\n\n# Set if missing\nexport OPENAI_API_KEY=\"your-key-here\"\n```\n\n**🚨 Out of Memory Issues**\n```bash\n# Increase heap size for large codebases\nexport JAVA_OPTS=\"-Xmx8g -XX:+UseG1GC\"\njava $JAVA_OPTS -jar target/waver-cli-0.1.0.jar [args...]\n```\n\n**🚨 Native Binary Issues**\n```bash\n# Check native binary permissions\nchmod +x target/waver-cli\n\n# Verify native dependencies\nldd target/waver-cli\n```\n\n**🚨 Debugging Pipeline Issues**\n```bash\n# Enable maximum verbosity\njava -jar target/waver-cli-0.1.0.jar \\\n  --verbose \\\n  --input ./problematic-code \\\n  --output ./debug-output \\\n  --type tutorial \\\n  --llm-provider OpenAI 2\u003e\u00261 | tee waver-debug.log\n```\n\n### Performance Benchmarks\n\n| Codebase Size | Processing Time (JAR) | Processing Time (Native) | Memory Usage |\n|---------------|----------------------|-------------------------|--------------|\n| Small (~50 files) | ~2-3 minutes | ~45-60 seconds | ~512MB |\n| Medium (~200 files) | ~8-12 minutes | ~3-5 minutes | ~1GB |\n| Large (~1000 files) | ~30-45 minutes | ~12-18 minutes | ~2-4GB |\n\n## 🚢 Production Deployment\n\nFor production environments, consider the **[waver-kubernetes](https://github.com/your-org/waver-kubernetes)** project which provides:\n\n- **Horizontal Pod Autoscaling** for processing large repositories\n- **Job Queues** with Redis for batch processing  \n- **Persistent Volumes** for generated documentation storage\n- **Monitoring \u0026 Metrics** with Prometheus and Grafana\n- **Resource Limits** and quality-of-service guarantees\n\n## 🛠️ Technical Stack\n\n- **Runtime**: Java 21+ (Virtual Threads, Pattern Matching, Records)\n- **AI Framework**: LangChain4j 1.0.0 (OpenAI GPT-4, Google Gemini)\n- **CLI Framework**: Picocli 4.7.7 (ANSI colors, auto-completion)\n- **Build System**: Maven 3.9+ (Shade plugin, Native profile)\n- **Native Compilation**: GraalVM Native Image (SubstrateVM)\n- **Pipeline Engine**: JGraphlet Task Pipeline (Concurrent execution)\n- **Code Analysis**: Custom AST parsing and pattern recognition\n- **Output Generation**: FlexMark (Markdown), Flying Saucer (PDF)\n\n## 📊 API Rate Limits \u0026 Costs\n\n### OpenAI GPT-4 Recommendations\n```bash\n# For cost optimization, use fewer input tokens\nexport WAVER_MAX_CONTEXT_SIZE=8192\n\n# Monitor usage with verbose logging\njava -jar waver-cli.jar --verbose [args...] 2\u003e\u00261 | grep \"tokens\"\n```\n\n### Google Gemini Optimization\n```bash\n# Gemini offers better value for large codebases\nexport WAVER_BATCH_SIZE=5  # Process files in batches\n```\n\n## 🤝 Contributing\n\nWe welcome contributions from the technical community! \n\n```bash\n# Development setup\ngit clone \u003crepo-url\u003e\ncd waver\nmvn clean compile\nmvn exec:java -Dexec.mainClass=\"dev.shaaf.waver.cli.Main\" -Dexec.args=\"--help\"\n\n# Run tests\nmvn test\n\n# Integration testing with testcontainers\nmvn integration-test\n```\n\n## 📄 License\n\nLicensed under the MIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**🔥 Ready to revolutionize your code documentation?**  \nDeploy Waver today and let AI transform your codebase into comprehensive, intelligent tutorials that your team will actually read and understand.\n\n```bash\n# Get started in 60 seconds\ngit clone \u003crepo\u003e \u0026\u0026 cd waver \u0026\u0026 mvn clean package -Pnative\nexport OPENAI_API_KEY=\"your-key\"\n./target/waver-cli --input ./your-project --output ./docs --type tutorial --llm-provider OpenAI\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaaf%2Fwaver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshaaf%2Fwaver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaaf%2Fwaver/lists"}