@smartergpt/lexrunner 1.0.0

package/docs/troubleshooting.md

@@ -0,0 +1,745 @@
+# Troubleshooting Guide
+
+Common issues, solutions, and debugging techniques for lexrunner.
+
+## Quick Diagnostics
+
+Always start with the doctor command:
+
+```bash
+lex-pr doctor
+```
+
+This validates:
+
+- Node.js and npm versions
+- Git configuration
+- GitHub token (if provided)
+- Workspace configuration
+- Profile directory resolution
+
+## Common Issues
+
+### Installation & Setup
+
+#### Issue: `command not found: lex-pr`
+
+**Cause:** Package not installed globally or not in PATH.
+
+**Solutions:**
+
+```bash
+# Option 1: Install globally
+npm install -g lexrunner
+
+# Option 2: Use npx
+npx lexrunner init
+
+# Option 3: Use local installation
+npm install --save-dev lexrunner
+npx lex-pr init
+
+# Option 4: Add to package.json scripts
+{
+  "scripts": {
+    "lex-pr": "lex-pr"
+  }
+}
+npm run lex-pr -- init
+```
+
+#### Issue: `Error: Cannot find module 'lexrunner'`
+
+**Cause:** Dependencies not installed.
+
+**Solution:**
+
+```bash
+# In project directory
+npm install
+
+# Or clean reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### Issue: Node version mismatch
+
+**Cause:** Using incompatible Node.js version.
+
+**Solution:**
+
+```bash
+# Check required version
+cat .nvmrc
+# Output: 20.18.0
+
+# Use nvm to switch
+nvm install 20.18.0
+nvm use 20.18.0
+
+# Or use volta
+volta install node@20.18.0
+```
+
+### Configuration Issues
+
+#### Issue: `Could not detect GitHub repository`
+
+**Cause:** Running outside a Git repository or no GitHub remote configured.
+
+**Solutions:**
+
+```bash
+# Check Git remote
+git remote -v
+
+# If no remote, add one
+git remote add origin https://github.com/owner/repo.git
+
+# Or specify explicitly
+lex-pr discover --owner <owner> --repo <repo>
+
+# Or initialize workspace first
+lex-pr init
+```
+
+#### Issue: `Profile directory not found`
+
+**Cause:** Workspace not initialized or wrong directory.
+
+**Solutions:**
+
+```bash
+# Initialize workspace
+lex-pr init
+
+# Or specify profile directory
+lex-pr plan --profile-dir .smartergpt.local
+
+# Or use environment variable
+export LEX_PR_PROFILE_DIR=.smartergpt.local
+lex-pr plan
+```
+
+#### Issue: `Invalid configuration file: scope.yml`
+
+**Cause:** YAML syntax error or invalid schema.
+
+**Solution:**
+
+```bash
+# Validate YAML syntax
+cat .smartergpt/scope.yml | python -c 'import yaml, sys; yaml.safe_load(sys.stdin)'
+
+# Check example
+cat .smartergpt/scope.yml
+
+# Expected format:
+# target: main
+# filters:
+#   labels: ["ready-to-merge"]
+#   exclude_labels: ["wip"]
+```
+
+### GitHub API Issues
+
+#### Issue: `GitHub API Error: 401 Unauthorized`
+
+**Cause:** Missing or invalid GitHub token.
+
+**Solutions:**
+
+```bash
+# Set token via environment
+export GITHUB_TOKEN=ghp_your_token_here
+lex-pr discover
+
+# Or via CLI
+lex-pr init --github-token ghp_your_token_here
+
+# Verify token has required scopes
+# Minimum: repo (for private repos) or public_repo (for public repos)
+```
+
+#### Issue: `GitHub API Error: 403 Forbidden`
+
+**Cause:** Rate limit exceeded or insufficient permissions.
+
+**Solutions:**
+
+```bash
+# Check rate limit
+curl -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/rate_limit
+
+# Wait for rate limit reset or use authenticated requests
+# Authenticated: 5000 req/hour
+# Unauthenticated: 60 req/hour
+
+# Verify token permissions
+gh auth status
+```
+
+#### Issue: `GitHub API Error: 404 Not Found`
+
+**Cause:** Repository doesn't exist or no access.
+
+**Solutions:**
+
+```bash
+# Verify repository exists
+gh repo view owner/repo
+
+# Check token has access
+gh api repos/owner/repo
+
+# Verify owner and repo names
+lex-pr discover --owner <owner> --repo <repo>
+```
+
+### Plan Generation Issues
+
+#### Issue: `Unknown dependency: feature-b`
+
+**Cause:** Dependency references non-existent item.
+
+**Solution:**
+
+```yaml
+# In deps.yml or stack.yml
+# Ensure dependency names match item names exactly
+
+# ❌ Wrong
+items:
+  - name: feature-a
+    deps: ["feature-B"]  # Case mismatch!
+
+# ✅ Correct
+items:
+  - name: feature-a
+    deps: ["feature-b"]  # Exact match
+```
+
+#### Issue: `Cycle detected in dependency graph`
+
+**Cause:** Circular dependencies (A → B → A).
+
+**Enhanced Error Message (v0.1.0+):**
+
+```
+❌ Errors:
+
+Dependency cycle detected in plan
+
+Cycle path: feat-a → feat-b → feat-c → feat-a
+
+Dependency chain:
+  feat-a               depends on feat-b
+  feat-b               depends on feat-c
+  feat-c               depends on feat-a
+
+Suggestion: Consider removing the dependency from 'feat-c' to 'feat-a' to break the cycle
+```
+
+**Solutions:**
+
+```bash
+# 1. Validate plan to see detailed cycle information
+lex-pr schema validate plan.json
+
+# 2. Visualize dependencies to understand the cycle
+lex-pr schema validate plan.json --verbose
+
+# Output includes layers showing dependency order:
+# Layers (topological sort):
+#   Layer 0: base-feature
+#   Layer 1: feature-a, feature-b
+#   Layer 2: feature-c
+
+# 3. Fix by identifying and removing the circular reference
+# Example cycle: auth → api → database → auth
+# Solution: Remove one dependency, e.g., database should not depend on auth
+
+# 4. Common cycle patterns and fixes:
+
+# Pattern 1: Simple cycle (A ↔ B)
+# Before:
+# - feature-a: deps: [feature-b]
+# - feature-b: deps: [feature-a]
+# Fix: Remove dependency from B to A
+
+# Pattern 2: Longer cycle (A → B → C → A)
+# Before:
+# - feature-a: deps: [feature-b]
+# - feature-b: deps: [feature-c]
+# - feature-c: deps: [feature-a]
+# Fix: Remove the "weakest" dependency (usually the last one)
+
+# Pattern 3: Self-dependency (A → A)
+# Before:
+# - feature-a: deps: [feature-a]
+# Fix: Remove self-reference
+
+# 5. Verify fix with validation
+lex-pr schema validate plan.json --verbose
+```
+
+**Prevention:**
+
+```bash
+# Always validate plans before execution
+lex-pr schema validate plan.json
+
+# Use --validate-cycles flag when generating plans (default: enabled)
+lex-pr plan --from-github --validate-cycles
+
+# Enable validation in CI/CD
+lex-pr schema validate plan.json || exit 1
+```
+
+#### Issue: `Orphan PRs detected` (Warning)
+
+**Cause:** Plan items with no dependencies and no dependents - execute in isolation.
+
+**Warning Message:**
+
+```
+⚠️  Warnings:
+
+Item 'orphan-feature' has no dependencies and no dependents (orphan)
+Suggestion: Consider if these items should have dependencies or dependents.
+```
+
+**Why This Matters:**
+
+Orphan items may indicate:
+
+- Forgotten dependency declarations
+- Features that should be grouped with others
+- Independent work that doesn't need the merge pyramid
+
+**Solutions:**
+
+```bash
+# 1. Review orphan items
+lex-pr schema validate plan.json --verbose
+
+# 2. Decide if orphan is intentional:
+
+# Option A: Add dependencies if the item should be part of the merge flow
+# In deps.yml or stack.yml:
+items:
+  - name: orphan-feature
+    deps: [base-feature]  # Link to dependency chain
+
+# Option B: Add label to mark as intentionally orphan (future)
+# In PR description:
+# Labels: orphan
+# This signals the item is meant to be independent
+
+# Option C: Merge orphans separately
+# Extract orphans to separate plan:
+lex-pr plan --from-github | jq '.items[] | select(.deps | length == 0)' > orphans.json
+
+# 3. Verify fix
+lex-pr schema validate plan.json
+```
+
+**When Orphans Are OK:**
+
+- Hotfixes that need immediate merge
+- Documentation updates
+- Independent features with no shared code
+- Experimental branches
+
+#### Issue: `Invalid dependency reference`
+
+**Cause:** Dependency name doesn't match any item in the plan.
+
+**Enhanced Error Message:**
+
+```
+❌ Errors:
+
+Item 'feature-a' references unknown dependency 'feature-missing'
+
+Suggestion: Ensure 'feature-missing' exists in the plan or remove it from 'feature-a' dependencies
+```
+
+**Solutions:**
+
+```bash
+# 1. Validate to see all invalid references
+lex-pr schema validate plan.json
+
+# 2. Check item names vs dependency names
+cat plan.json | jq '.items[] | {name, deps}'
+
+# 3. Common causes:
+
+# Typo in dependency name
+# Before: deps: ["feat-a"]
+# After:  deps: ["feature-a"]
+
+# Case mismatch
+# Before: deps: ["Feature-A"]
+# After:  deps: ["feature-a"]
+
+# Reference to deleted/renamed item
+# Before: deps: ["old-name"]
+# After:  deps: ["new-name"]
+
+# 4. Fix and revalidate
+lex-pr schema validate plan.json
+```
+
+#### Issue: `No PRs found matching scope`
+
+**Cause:** Scope filters too restrictive or no matching PRs.
+
+**Solutions:**
+
+```bash
+# Check discovered PRs
+lex-pr discover
+
+# Relax scope.yml filters
+# Before:
+# filters:
+#   labels: ["ready-to-merge", "approved"]
+#
+# After:
+# filters:
+#   labels: ["ready-to-merge"]
+
+# Or discover without filters
+lex-pr discover --state open
+```
+
+### Gate Execution Issues
+
+#### Issue: `Gate failed: npm test`
+
+**Cause:** Tests failing in plan items.
+
+**Debug Steps:**
+
+```bash
+# 1. Check gate output
+cat gate-results/item-name/gate-name.json | jq '.meta'
+
+# 2. View detailed logs
+cat gate-results/item-name/gate-name.stderr.log
+
+# 3. Run gate manually
+cd /path/to/pr-branch
+npm test
+
+# 4. Check gate configuration
+cat .smartergpt/gates.yml
+```
+
+#### Issue: `Gate timeout exceeded`
+
+**Cause:** Gate command running longer than timeout.
+
+**Solutions:**
+
+```yaml
+# Increase timeout in gates.yml
+gates:
+  - name: slow-test
+    command: npm run integration-test
+    timeout: 600  # 10 minutes instead of default 300
+
+# Or via environment
+export LEX_PR_TIMEOUT=600
+lex-pr execute plan.json
+```
+
+#### Issue: `Gate execution failed: command not found`
+
+**Cause:** Gate command not available in PATH.
+
+**Solutions:**
+
+```bash
+# Use absolute paths
+# gates.yml:
+gates:
+  - name: custom-check
+    command: /usr/local/bin/custom-check
+
+# Or relative to workspace
+gates:
+  - name: custom-check
+    command: ./scripts/custom-check.sh
+
+# Ensure script is executable
+chmod +x ./scripts/custom-check.sh
+```
+
+### Merge Operation Issues
+
+#### Issue: `Merge failed: Cannot fast-forward`
+
+**Cause:** Merge conflicts or diverged branches.
+
+**Solution:**
+
+```bash
+# Run with --dry-run first
+lex-pr merge plan.json --dry-run
+
+# Check conflict analysis
+lex-pr merge plan.json --analyze
+
+# Manual conflict resolution required
+git checkout feature-branch
+git merge main
+# Resolve conflicts
+git add .
+git commit
+```
+
+#### Issue: `Merge blocked: Gates not passing`
+
+**Cause:** Quality gates failed.
+
+**Solution:**
+
+```bash
+# Check which gates failed
+lex-pr report gate-results --out md
+
+# Re-run specific gate
+lex-pr execute plan.json --item feature-a --gate test
+
+# Skip gates (not recommended for production)
+lex-pr merge plan.json --skip-gates
+```
+
+#### Issue: `Dry-run only, use --execute to merge`
+
+**Cause:** Default behavior is dry-run for safety.
+
+**Solution:**
+
+```bash
+# This is expected! Dry-run is the default
+lex-pr merge plan.json --dry-run
+
+# To actually merge, use --execute
+lex-pr merge plan.json --execute
+```
+
+## Debugging Techniques
+
+### Enable Verbose Logging
+
+```bash
+# Set log level
+export LOG_LEVEL=debug
+lex-pr plan
+
+# Or use --verbose flag (if available)
+lex-pr plan --verbose
+```
+
+### Inspect Generated Plan
+
+```bash
+# Pretty-print plan
+cat plan.json | jq '.'
+
+# Check dependency graph
+cat plan.json | jq '.items[] | {name, deps}'
+
+# Verify merge order
+lex-pr merge-order plan.json
+```
+
+### Validate Configuration
+
+```bash
+# Check schema validation
+lex-pr schema validate plan.json
+
+# Dump effective configuration
+lex-pr doctor --json | jq '.'
+
+# Verify profile resolution
+lex-pr doctor | grep "using profile"
+```
+
+### Test Gates Manually
+
+```bash
+# Extract gate command
+cat .smartergpt/gates.yml | grep -A 3 "name: test"
+
+# Run in isolation
+cd /path/to/pr-branch
+npm test  # Or whatever the gate command is
+
+# Check exit code
+echo $?  # Should be 0 for success
+```
+
+### Analyze Gate Results
+
+```bash
+# List all gate results
+ls -la gate-results/
+
+# Check specific result
+cat gate-results/feature-a/test.json | jq '.'
+
+# View failure logs
+cat gate-results/feature-a/test.stderr.log
+
+# Aggregate results
+lex-pr report gate-results --out md
+```
+
+## Advanced Troubleshooting
+
+### Determinism Issues
+
+**Symptom:** Same inputs producing different outputs.
+
+**Debug:**
+
+```bash
+# Run twice and compare
+lex-pr plan --out .artifacts1
+lex-pr plan --out .artifacts2
+
+# Byte-level comparison
+diff -u .artifacts1/plan.json .artifacts2/plan.json
+
+# Should be identical - if not, file a bug
+cmp .artifacts1/plan.json .artifacts2/plan.json
+```
+
+### Performance Issues
+
+**Symptom:** Slow gate execution or planning.
+
+**Debug:**
+
+```bash
+# Profile plan generation
+time lex-pr plan
+
+# Check gate parallelism
+export LEX_PR_MAX_WORKERS=4
+lex-pr execute plan.json
+
+# Monitor resource usage
+top  # Check CPU/memory while running
+```
+
+### Profile Resolution Issues
+
+**Symptom:** Wrong profile being used.
+
+**Debug:**
+
+```bash
+# Check resolution order
+lex-pr doctor
+
+# Output shows:
+# lexrunner using profile: /path/to/profile (role: local)
+
+# Verify files exist
+ls -la .smartergpt.local/
+ls -la .smartergpt/
+
+# Check environment
+env | grep LEX_PR
+```
+
+## Getting Help
+
+### Self-Service Resources
+
+1. **Documentation**: Check `docs/` directory
+   - [Quickstart Guide](./quickstart.md)
+   - [CLI Reference](./cli.md)
+   - [Architecture Overview](./architecture.md)
+
+2. **Examples**: Review `examples/` directory
+   - GitHub integration examples
+   - CI/CD pipeline examples
+
+3. **Tests**: Look at test files for usage patterns
+   - `tests/*.spec.ts`
+   - `tests/integration-*.test.ts`
+
+### Community Support
+
+1. **GitHub Issues**: Search existing issues
+
+   ```bash
+   # Search issues
+   gh issue list --search "error message"
+   ```
+
+2. **Discussions**: Check GitHub Discussions for Q&A
+
+3. **Bug Reports**: File issues with:
+   - Output of `lex-pr doctor`
+   - Minimal reproduction steps
+   - Expected vs actual behavior
+   - Relevant logs/error messages
+
+### Debug Information to Collect
+
+When filing issues, include:
+
+```bash
+# 1. Version information
+lex-pr --version
+node --version
+npm --version
+
+# 2. Environment validation
+lex-pr doctor
+
+# 3. Configuration files
+cat .smartergpt/scope.yml
+cat .smartergpt/gates.yml
+cat .smartergpt/profile.yml
+
+# 4. Error output (sanitized)
+lex-pr plan 2>&1 | tee error.log
+
+# 5. Minimal reproduction
+# Share smallest possible plan.json or config that reproduces issue
+```
+
+## Known Limitations
+
+### Current Limitations
+
+1. **GitHub Only**: Only supports GitHub (GitLab/Bitbucket coming)
+2. **Local Execution**: No distributed/cloud execution
+3. **Sequential Merges**: Merges execute sequentially (by design)
+4. **No Auto-Conflict Resolution**: Manual intervention needed for conflicts
+
+### Workarounds
+
+1. **Other Git Hosts**: Use GitHub mirror or API adapters
+2. **Remote Execution**: Use CI/CD runners (see [integrations](./integrations/))
+3. **Parallel Merges**: Not supported (ensures dependency order)
+4. **Conflict Resolution**: Use weave contract (see [weave-contract.md](./weave-contract.md))
+
+## Related Documentation
+
+- [CLI Reference](./cli.md) - Complete command documentation
+- [Error Taxonomy](./errors.md) - Error codes and handling
+- [Architecture Overview](./architecture.md) - System design
+- [Migration Guide](./migration-guide.md) - Migrating from manual processes