feat: add 4 real-world workflow examples for promptext library

[1broseidon]

This PR adds four production-ready examples demonstrating how to use the promptext library for real-world AI-powered development workflows. Each example includes comprehensive documentation and is ready to use.

1. Code Search (examples/code-search/)

Natural language code search tool that helps developers find relevant code across large codebases.

What it does:

• Converts natural language queries into search keywords
• Uses relevance filtering to find matching files
• Scores results by filename, directory, imports, and content
• Provides AI-ready context for follow-up analysis

Example usage:

go run main.go "Where is user authentication handled?"
go run main.go "How do we connect to the database?"

Use cases:

• Understanding unfamiliar codebases
• Finding implementation examples
• Locating bug sources
• Building IDE extensions

2. CI Code Review (examples/ci-code-review/)

Automated PR code reviewer for GitHub Actions that provides AI-powered code analysis and feedback.

What it does:

• Detects changed files in pull requests
• Extracts relevant code context for review
• Integrates with Claude, GPT, or other AI providers
• Posts review comments back to PRs

Example usage:

# Get context for PR #123
go run main.go 123

# With custom base branch
go run main.go 456 develop

Use cases:

• Automated code quality checks in CI/CD
• Security vulnerability detection
• Style guide enforcement
• Educational feedback for junior developers

Includes:

• Complete GitHub Actions workflow (.github/workflows/ai-review.yml)
• Integration examples for Claude and GPT APIs
• Best practices for effective AI code review

3. Doc Generator (examples/doc-generator/)

Automated documentation generator that creates API docs, READMEs, guides, and examples from your codebase using AI.

What it does:

• Extracts code with different strategies per doc type
• Optimizes token usage for focused documentation
• Supports multiple documentation formats
• Integrates with AI providers for content generation

Example usage:

# Generate API documentation
go run main.go api /path/to/project

# Create README from codebase
go run main.go readme /path/to/project

# Generate developer guide
go run main.go guide /path/to/project

Doc types:

• api: Public API documentation (exported types only)
• readme: Project overview and getting started
• guide: In-depth developer documentation
• examples: Usage examples from actual code

Use cases:

• Keeping docs in sync with code
• Auto-generating API references
• Creating onboarding materials
• Documenting legacy codebases

4. Migration Assistant (examples/migration-assistant/)

Helps modernize legacy codebases through a structured 4-phase approach using AI-powered analysis and planning.

What it does:

• Phase 1 (analyze): Deep dive into legacy patterns and issues
• Phase 2 (plan): Create systematic migration strategy
• Phase 3 (migrate): Execute with focused context per component
• Phase 4 (verify): Validate changes and ensure correctness

Example usage:

# Analyze legacy component
go run main.go analyze /path/to/legacy authentication

# Create migration plan
go run main.go plan /path/to/legacy authentication

# Get migration context
go run main.go migrate /path/to/legacy authentication

# Verify after migration
go run main.go verify /path/to/legacy authentication

Detection capabilities:

• Security issues (weak crypto, SQL injection, etc.)
• Deprecated APIs and patterns
• Global state and tight coupling
• Performance anti-patterns

Use cases:

• Modernizing legacy applications
• Security updates and audits
• Framework migrations (e.g., migrating to Go 1.21+)
• Refactoring monoliths to microservices

Common Features

All examples include:

• ✅ Comprehensive README with usage examples
• ✅ AI provider integration (Claude, GPT, local LLMs)
• ✅ Token budget management for different AI models
• ✅ Production-ready error handling
• ✅ Real-world workflow examples
• ✅ Best practices and troubleshooting

Testing

All examples have been tested and compile successfully:

cd examples/code-search && go build
cd examples/ci-code-review && go build
cd examples/doc-generator && go build
cd examples/migration-assistant && go build

These examples demonstrate the power and flexibility of the promptext library for building AI-powered development tools.

[claude]

🤖 Code Review: Real-World Workflow Examples

Thank you for this comprehensive PR adding four production-ready examples! This is a significant contribution that demonstrates the practical applications of the promptext library. Here's my detailed review:

---

✅ Strengths

Documentation Quality

• Excellent README files: Each example has comprehensive documentation with clear usage examples, use cases, and troubleshooting sections
• Well-commented code: All four examples include detailed package-level comments and inline documentation
• Real-world focus: Examples address actual developer needs (code search, CI review, documentation, migration)

Code Organization

• Consistent structure: All examples follow a similar pattern making them easy to understand
• Good separation of concerns: Each example has clearly defined functions with single responsibilities
• Reusable patterns: The examples serve as good templates for developers building similar tools

GitHub Actions Integration

• Complete workflow: The CI code review example includes a full, production-ready GitHub Actions workflow
• Good commenting: The workflow file is well-documented with clear setup instructions

---

🔍 Issues & Concerns

1. Security - Command Injection Risk (Medium Severity)

Location: examples/ci-code-review/main.go:117

diffCmd := fmt.Sprintf("git diff --name-only %s...%s", info.BaseBranch, info.HeadBranch)
changedFiles, err := runGitCommand("sh", "-c", diffCmd)

Issue: Branch names from environment variables are directly interpolated into shell commands without sanitization. A malicious user could potentially inject commands via branch names.

Recommendation: Use direct git command execution instead of shell:

changedFiles, err := runGitCommand("git", "diff", "--name-only", 
    fmt.Sprintf("%s...%s", info.BaseBranch, info.HeadBranch))

2. Error Handling - Silent Failures (Low-Medium Severity)

Locations:

• examples/code-search/main.go:106
• examples/ci-code-review/main.go:226

if err := os.WriteFile(outputFile, []byte(result.FormattedOutput), 0644); err != nil {
    fmt.Fprintf(os.Stderr, "Warning: Could not save results to file: %v\n", err)
} 

Issue: File write errors are logged but execution continues. This could lead to confusion if users expect output files to exist.

Recommendation: Consider making file write failures more visible or offering a --no-save flag for when file output isn't needed.

3. Potential Bug - Directory Traversal (Low Severity)

Location: examples/doc-generator/main.go:138

if err := os.MkdirAll(filepath.Dir(config.OutputFile), 0755); err != nil {
    return fmt.Errorf("failed to create output directory: %w", err)
}

Issue: User-provided output paths aren't validated. A user could specify paths like ../../etc/docs/api.md.

Recommendation: Validate and sanitize output paths, or restrict to specific directories.

4. GitHub Actions - Outdated Action Version

Location: examples/ci-code-review/.github/workflows/ai-review.yml:76

- name: Upload Review Context
  uses: actions/upload-artifact@v3

Issue: Using v3 of upload-artifact when v4 is available and recommended.

Recommendation: Update to actions/upload-artifact@v4 for better performance and features.

---

🎯 Code Quality Observations

Best Practices ✅

• Good use of types: Custom types like PRInfo, MigrationPhase, DocType improve code readability
• Proper error wrapping: Using fmt.Errorf with %w for error chains
• Consistent formatting: All code follows Go conventions
• User-friendly output: Excellent use of emoji and formatting for CLI output

Minor Improvements Suggested

A. Magic Numbers

Location: Multiple files (e.g., code-search/main.go:149)

if len(word) < 3 || stopWords[word] {

Consider extracting as named constants:

const minKeywordLength = 3

B. Duplicate Code Pattern

All four examples have similar file-saving logic. Consider extracting to a shared utility package:

// pkg/exampleutil/files.go
func SaveArtifacts(dir string, files map[string][]byte) error {
    // Shared save logic
}

C. Keyword Extraction Could Be More Robust

Location: examples/code-search/main.go:121-166

The extractKeywords function is basic. Consider:

• Stemming words (e.g., "authentication" → "auth")
• Supporting multi-word phrases
• Adding domain-specific keywords for code (e.g., "func", "class", "interface")

---

🔬 Performance Considerations

Good ✅

• Appropriate token budgets: Each example sets reasonable token limits for its use case
• Efficient file filtering: Using promptext's built-in filtering rather than custom solutions
• Minimal memory overhead: Streaming-friendly approach with file operations

Observations

1. Migration Assistant: Token budget of 30,000 (line 257) could be expensive for large codebases. Consider documenting cost implications.
2. No caching: For repeated operations (e.g., multiple CI runs on same commit), consider caching promptext results
3. Parallel processing: The doc-generator's generateAllDocs runs sequentially - could be parallelized

---

🔒 Security Assessment

Issues Found

1. Command injection risk (documented above in Issue Add Claude Code GitHub Workflow #1)
2. Environment variable trust: PR author and title from environment variables are not sanitized before use in file names/content
3. No input validation: File paths, component names, and other user inputs lack validation

Recommendations

1. Sanitize all environment variables before use
2. Validate file paths to prevent directory traversal
3. Consider rate limiting for AI API calls in production workflows
4. Add warnings about sensitive data in examples/READMEs (e.g., don't commit API keys)

---

🧪 Test Coverage

Missing Tests ❌

Critical Gap: No test files found for any of the four examples.

Recommendation: Add at least basic tests:

// examples/code-search/main_test.go
func TestExtractKeywords(t *testing.T) {
    tests := []struct {
        query    string
        expected []string
    }{
        {
            query:    "Where is user authentication handled?",
            expected: []string{"user", "authentication", "handled"},
        },
    }
    
    for _, tt := range tests {
        result := extractKeywords(tt.query)
        // assertions
    }
}

Consider adding:

• Unit tests for keyword extraction
• Integration tests that verify promptext API usage
• Test fixtures for git operations
• CI workflow validation (yamllint, actionlint)

---

📚 Documentation Improvements

Add to READMEs

1. Cost implications: Document approximate API costs for AI review runs
2. Rate limits: Warn about GitHub API rate limits
3. Troubleshooting: Add section on common git-related errors
4. Prerequisites: Clearly state git version requirements

Missing Examples

• Error scenarios: What happens when no files match?
• Large repositories: How to handle monorepos with 1000+ files?
• Private repositories: Authentication requirements

---

💡 Suggestions for Enhancement

Short-term

1. Add input validation and sanitization
2. Update GitHub Actions to v4
3. Add basic unit tests
4. Extract magic numbers to constants

Medium-term

1. Create shared utility package for common code
2. Add integration tests
3. Implement caching for repeated operations
4. Add support for configuration files (e.g., .ai-review.yml)

Long-term

1. Build a CLI tool that combines all four examples
2. Add telemetry/analytics (opt-in)
3. Create a web UI for visualization
4. Add support for other CI systems (GitLab, BitBucket)

---

🎯 Final Verdict

Overall Assessment: APPROVE with Suggestions ✅

This is a high-quality PR that significantly enhances the value of the promptext library. The examples are:

• Well-documented
• Production-ready (with minor security fixes)
• Address real developer pain points
• Serve as excellent templates

Must-Fix Before Merge

1. ❗ Security: Fix command injection vulnerability in ci-code-review/main.go:117

Strongly Recommended

1. Update GitHub Actions to v4
2. Add input validation for file paths
3. Add at least basic unit tests for keyword extraction

Nice to Have

1. Extract common utilities
2. Add more comprehensive documentation
3. Implement caching

---

📊 Metrics

• Files Added: 12 (4 Go files, 4 READMEs, 1 workflow, 3 other docs)
• Lines of Code: ~3,472 additions
• Documentation: Excellent (comprehensive READMEs)
• Test Coverage: 0% (no tests included)
• Security Issues: 1 medium, 2 low
• Code Quality: High

---

🙏 Conclusion

Excellent work on these examples! They're comprehensive, well-documented, and demonstrate real-world value. The security issue should be addressed before merge, but overall this is a fantastic addition to the project.

The examples will help developers understand how to integrate promptext into their workflows and serve as templates for building custom AI-powered tools.

Estimated review time: 45 minutes
Recommended action: Approve after addressing the command injection security issue

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com