@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/lsp_orchestrator/docs/how-to-guides/project-tool-detection.md

@@ -1,320 +0,0 @@
-# Project Tool Detection
-
-## How Auto-Detection Works
-
-The VDS LSP Orchestrator detects project tools using a priority-based approach:
-
-1. **Lock files** (fastest, highest confidence)
-   - `uv.lock` → UV
-   - `poetry.lock` → Poetry
-   - `pdm.lock` → PDM
-   - `Pipfile.lock` → Pipenv
-
-2. **Config sections**
-   - `[tool.uv]` → UV
-   - `[tool.mypy]` → mypy
-   - `[tool.ruff]` → ruff
-
-3. **Dependencies**
-   - Check `project.dependencies` in pyproject.toml
-
-4. **Commands**
-   - Check if tool is available in PATH
-
-## Detecting Your Project Tools
-
-### Basic Usage
-
-```bash
-cd your-project
-vds-lsp detect-tools
-```
-
-Output:
-```
-┏━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
-┃ Category       ┃ Tool   ┃ Details    ┃
-┡━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
-│ Package Manager│ uv     │ uv sync    │
-│ Type Checker   │ mypy   │            │
-│ Formatter      │ ruff   │ ruff format│
-│ Linter         │ ruff   │ ruff check │
-│ Test Runner    │ pytest │ pytest     │
-└────────────────┴────────┴────────────┘
-```
-
-### JSON Output
-
-```bash
-vds-lsp detect-tools --json
-```
-
-Output:
-```json
-{
-  "package_manager": {
-    "tool": "uv",
-    "source": "uv.lock",
-    "confidence": "high",
-    "install_command": "uv sync"
-  },
-  "type_checker": {
-    "tool": "mypy",
-    "source": "mypy.ini",
-    "confidence": "high",
-    "check_command": "mypy"
-  },
-  "formatter": {
-    "tool": "ruff",
-    "source": "[tool.ruff]",
-    "confidence": "high",
-    "format_command": "ruff format"
-  },
-  "linter": {
-    "tool": "ruff",
-    "source": "[tool.ruff]",
-    "confidence": "high",
-    "lint_command": "ruff check"
-  },
-  "test_runner": {
-    "tool": "pytest",
-    "source": "dependencies",
-    "confidence": "medium",
-    "test_command": "pytest"
-  }
-}
-```
-
-## Overriding Auto-Detection
-
-### CLI Flag
-
-```bash
-# Override type checker for a single command
-vds-lsp type-check src/ --type-checker mypy
-vds-lsp type-check src/ --type-checker basedpyright
-```
-
-### Configuration File
-
-Create `.vds-lsp/config.json`:
-```bash
-mkdir -p .vds-lsp
-cat > .vds-lsp/config.json << 'EOF'
-{
-  "typeChecker": "mypy"
-}
-EOF
-```
-
-### Environment Variable
-
-```bash
-# Set for current session
-export VDS_LSP_TYPE_CHECKER=mypy
-vds-lsp type-check src/
-
-# Set permanently (add to ~/.bashrc or ~/.zshrc)
-echo 'export VDS_LSP_TYPE_CHECKER=mypy' >> ~/.bashrc
-```
-
-## Priority Order
-
-When multiple sources specify a type checker, the priority order is:
-
-1. **CLI flag** (`--type-checker`) - Highest priority
-2. **Configuration file** (`.vds-lsp/config.json`) - Takes precedence over env var
-3. **Environment variable** (`VDS_LSP_TYPE_CHECKER`) - Only used if no config file
-4. **Auto-detection** - Lowest priority (fallback)
-
-## Type Checker Selection
-
-### Supported Type Checkers
-
-| Type Checker | Description | When to Use |
-|--------------|-------------|-------------|
-| `auto` | Auto-detect from project (default) | Most projects |
-| `mypy` | Standard Python type checker | Projects with mypy.ini |
-| `basedpyright` | Fast, feature-rich type checker | Modern Python projects |
-| `pyright` | Microsoft's type checker | VS Code users |
-| `pylsp` | Language Server Protocol wrapper | When using pylsp |
-
-### Mypy Integration
-
-If your project uses mypy, the orchestrator will automatically detect it:
-
-```bash
-# Detection triggers for mypy:
-- mypy.ini exists in project root
-- [tool.mypy] section in pyproject.toml
-- mypy in project.dependencies
-- mypy command available in PATH
-```
-
-### Mypy Configuration
-
-The orchestrator respects your existing mypy configuration:
-
-**mypy.ini**:
-```ini
-[mypy]
-python_version = 3.12
-warn_return_any = True
-warn_unused_configs = True
-disallow_untyped_defs = True
-```
-
-**pyproject.toml**:
-```toml
-[tool.mypy]
-python_version = "3.12"
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = true
-```
-
-## Type Checker Comparison
-
-### Mypy vs BasedPyright
-
-| Feature | Mypy | BasedPyright |
-|---------|------|--------------|
-| Speed | Moderate | Fast |
-| Configuration | mypy.ini/pyproject.toml | pyrightconfig.json/pyproject.toml |
-| Type: Ignore | `# type: ignore` | `# type: ignore` |
-| Daemon Mode | dmypy | Built-in |
-| IDE Support | Excellent | Excellent |
-| Community | Mature | Growing |
-
-## Detection Caching
-
-Detection results are cached in `.vds-lsp/cache/tool_detection.json` for performance.
-
-### Cache Invalidation
-
-Cache automatically invalidates when:
-- `pyproject.toml` is modified
-- 1 hour expires since last detection
-
-### Manual Cache Clear
-
-```bash
-rm -f .vds-lsp/cache/tool_detection.json
-```
-
-## Examples
-
-### UV Project with mypy
-
-```bash
-$ vds-lsp detect-tools
-┏━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
-┃ Category       ┃ Tool   ┃ Details    ┃
-┡━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
-│ Package Manager│ uv     │ uv.lock    │
-│ Type Checker   │ mypy   │ mypy.ini   │
-│ Formatter      │ ruff   │ [tool.ruff]│
-│ Linter         │ ruff   │ [tool.ruff]│
-│ Test Runner    │ pytest │ deps       │
-└────────────────┴────────┴────────────┘
-```
-
-### Poetry Project
-
-```bash
-$ vds-lsp detect-tools
-┏━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
-┃ Category       ┃ Tool   ┃ Details    ┃
-┡━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
-│ Package Manager│ poetry │ poetry.lock│
-│ Type Checker   │ based  │ default    │
-│ Formatter      │ black  │ deps       │
-│ Linter         │ flake8 │ deps       │
-│ Test Runner    │ pytest │ deps       │
-└────────────────┴────────┴────────────┘
-```
-
-### PDM Project
-
-```bash
-$ vds-lsp detect-tools
-┏━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
-┃ Category       ┃ Tool   ┃ Details    ┃
-┡━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
-│ Package Manager│ pdm    │ pdm.lock   │
-│ Type Checker   │ based  │ default    │
-│ Formatter      │ ruff   │ [tool.ruff]│
-│ Linter         │ ruff   │ [tool.ruff]│
-│ Test Runner    │ pytest │ deps       │
-└────────────────┴────────┴────────────┘
-```
-
-## Dry Run Mode
-
-Preview what would be checked without actually running type checking:
-
-```bash
-vds-lsp type-check src/ --dry-run
-```
-
-Output:
-```
-[yellow]Would check:[/yellow] src/vds_lsp_orchestrator, src/tests
-[cyan]Type checker:[/cyan] mypy
-[cyan]Mode:[/cyan] standard
-```
-
-## Troubleshooting
-
-### Type Checker Not Detected
-
-**Problem**: Wrong type checker selected or none detected.
-
-**Solutions**:
-```bash
-# Explicitly specify type checker
-vds-lsp type-check src/ --type-checker mypy
-
-# Check what was detected
-vds-lsp detect-tools
-
-# Clear cache and retry
-rm -f .vds-lsp/cache/tool_detection.json
-vds-lsp detect-tools
-```
-
-### Package Manager Misidentified
-
-**Problem**: Wrong package manager detected.
-
-**Solution**: Lock files take priority. Ensure only one lock file exists:
-```bash
-ls -la *.lock  # Should show only one of: uv.lock, poetry.lock, pdm.lock, Pipfile.lock
-```
-
-### Tool Not Found
-
-**Problem**: Tool detected but not available in PATH.
-
-**Solution**: Install the tool or use a different one:
-```bash
-# Install mypy
-uv add --dev mypy
-
-# Or use basedpyright (bundled)
-vds-lsp type-check src/ --type-checker basedpyright
-```
-
-## Best Practices
-
-1. **Use lock files** for reliable package manager detection
-2. **Keep config in pyproject.toml** for consistent tool detection
-3. **Explicit overrides** in CI/CD for predictable behavior
-4. **Cache awareness** - understanding cache behavior for debugging
-5. **Dry run first** - use `--dry-run` to verify configuration before large checks
-
-## See Also
-
-- [Configuration Reference](../reference/configuration.md) - Complete configuration options
-- [Command Reference](../reference/commands.md) - CLI command documentation
-- [Type Check Code](type-check-code.md) - Type checking usage guide

package/tools/vds-scripts/lsp_orchestrator/docs/how-to-guides/type-check-code.md

@@ -1,46 +0,0 @@
-# How to Type Check Python Code
-
-Check your Python code for type errors using BasedPyright.
-
----
-
-## Check a Single File
-
-```bash
-vds-lsp type-check src/app.py
-```
-
-## Check a Directory
-
-```bash
-vds-lsp type-check src/
-```
-
-## Use Strict Mode
-
-For stricter type checking:
-
-```bash
-vds-lsp type-check src/ --mode strict
-```
-
-Available modes: `basic`, `standard` (default), `strict`
-
-## Get JSON Output
-
-For scripting and automation:
-
-```bash
-vds-lsp --json-only type-check src/ > type-results.json
-```
-
-## Filter by File Pattern
-
-```bash
-vds-lsp type-check src/ --include "**/api/**" --exclude "**/tests/**"
-```
-
-## See Also
-
-- [How to Fix Type Errors](fix-errors.md)
-- [Command Reference: type-check](../reference/commands.md#type-check)

package/tools/vds-scripts/lsp_orchestrator/docs/how-to-guides/use-daemon-mode.md

@@ -1,78 +0,0 @@
-# How to Use Daemon Mode
-
-Run the LSP server persistently for instant responses.
-
----
-
-## Start the Daemon
-
-```bash
-vds-lsp daemon start
-```
-
-## Check Daemon Status
-
-```bash
-vds-lsp daemon status
-```
-
-**Expected output**:
-
-```
-┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Property  ┃ Value                                                            ┃
-┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ Running   │ Yes                                                              │
-│ PID       │ 56158                                                            │
-│ Socket    │ /tmp/vds-lsp-daemon/vds-lsp-f1a67163077cb984.sock                │
-│ Uptime    │ 0:05:23                                                          │
-│ Clients   │ 1                                                                │
-│ Workspace │ /path/to/workspace                                               │
-└───────────┴───────────────────────────────────────────────────────────────────┘
-```
-
-## Use LSP Commands
-
-All commands now use the daemon for instant responses:
-
-```bash
-vds-lsp hover src/app.py:10:5
-vds-lsp goto --file "src/app.py:10:5" my_function
-vds-lsp type-check src/
-```
-
-## Stop the Daemon
-
-```bash
-vds-lsp daemon stop
-```
-
-## Restart the Daemon
-
-```bash
-vds-lsp daemon restart
-```
-
-## Extend Idle Timeout
-
-By default, the daemon stops after 5 minutes of inactivity. To extend:
-
-```bash
-vds-lsp daemon start --idle-timeout 600
-```
-
-This sets the timeout to 600 seconds (10 minutes).
-
-## Performance Comparison
-
-| Mode | First Request | Subsequent Requests |
-|------|--------------|---------------------|
-| Direct | 1-3s | 1s each |
-| Daemon | 1s | <100ms |
-
----
-
-## See Also
-
-- [How to Automate with JSON Output](automate-with-json.md)
-- [Command Reference: Daemon](../reference/commands.md#daemon-management)

package/tools/vds-scripts/lsp_orchestrator/docs/how-to-guides/wsl2-optimization.md

@@ -1,227 +0,0 @@
-# WSL2 Optimization
-
-**Phase 11 Feature**: Automatic and manual optimizations for running VDS LSP Orchestrator on WSL2.
-
-## Overview
-
-WSL2 (Windows Subsystem for Linux 2) provides a Linux environment on Windows. However, the cross-filesystem access between Windows and Linux can impact LSP performance.
-
-VDS LSP Orchestrator includes automatic WSL2 detection and optimizations:
-- Automatic detection of WSL2 environment
-- Optimized file access patterns
-- Reduced cross-filesystem calls
-- Improved startup and response times
-
-## Auto-Detection
-
-By default, VDS LSP Orchestrator auto-detects WSL2:
-
-```bash
-# Auto-detection is enabled by default
-vds-lsp type-check src/
-vds-lsp diagnostics src/
-```
-
-The tool detects WSL2 by checking:
-- `/proc/version` for "Microsoft" or "WSL"
-- WSL-specific environment variables
-
-## Manual Configuration
-
-### Enable WSL2 Optimization
-
-If auto-detection fails, enable manually:
-
-```bash
-vds-lsp --wsl-optimize type-check src/
-```
-
-### Disable WSL2 Optimization
-
-If you're not using WSL2 or prefer native behavior:
-
-```bash
-vds-lsp --no-wsl-optimize type-check src/
-```
-
-## Configuration
-
-### Environment Variables
-
-```bash
-export VDS_LSP_WSL_OPTIMIZE=true
-```
-
-### Configuration File
-
-**`.vds-lsp/config.json`**:
-```json
-{
-  "wsl_optimize": true
-}
-```
-
-**`pyproject.toml`**:
-```toml
-[tool.vds-lsp]
-wsl-optimize = true
-```
-
-### CLI Flag
-
-```bash
-vds-lsp --wsl-optimize type-check src/
-vds-lsp --wsl-optimize diagnostics src/
-```
-
-## Performance Tips
-
-### Workspace Location
-
-For best performance on WSL2:
-- Keep your workspace in the Linux filesystem (e.g., `~/projects/`)
-- Avoid working in `/mnt/c/` (Windows filesystem)
-- Use `\\wsl$\` from Windows for file access, not drive letters
-
-**Recommended**:
-```bash
-# Good: Linux filesystem
-~/projects/my-project/
-
-# Avoid: Windows filesystem (slow)
-/mnt/c/projects/my-project/
-```
-
-### File Access Patterns
-
-WSL2 optimization reduces cross-filesystem calls:
-- Minimizes operations on `/mnt/` paths
-- Uses Linux-native paths when possible
-- Batches file operations to reduce overhead
-
-### Daemon Mode
-
-Combine WSL2 optimization with daemon mode for best performance:
-
-```bash
-# Start daemon with WSL2 optimization
-vds-lsp --wsl-optimize daemon start
-
-# Subsequent commands are fast
-vds-lsp hover src/app.py:10:5
-vds-lsp goto --file "src/app.py:10:5" my_function
-```
-
-## Troubleshooting
-
-### Slow Performance
-
-If you experience slowness:
-1. Verify your workspace is in the Linux filesystem
-2. Check if WSL2 optimization is enabled
-3. Consider using Docker mode for isolation
-
-```bash
-# Verify workspace location
-pwd  # Should be ~/... not /mnt/c/...
-
-# Check if optimization is active
-vds-lsp --verbose --wsl-optimize health
-```
-
-### Auto-Detection Issues
-
-If auto-detection fails:
-```bash
-# Enable manually
-vds-lsp --wsl-optimize type-check src/
-
-# Or set in config
-echo '{"wsl_optimize": true}' > .vds-lsp/config.json
-```
-
-### Path Issues
-
-Ensure you're using Linux paths, not Windows paths:
-```bash
-# Good: Linux path
-vds-lsp type-check ~/projects/my-project/src/
-
-# Avoid: Windows path
-vds-lsp type-check /mnt/c/projects/my-project/src/
-```
-
-## Examples
-
-### Type Checking with WSL2 Optimization
-
-```bash
-# Auto-detected
-vds-lsp type-check src/
-
-# Explicitly enabled
-vds-lsp --wsl-optimize type-check src/
-
-# With daemon mode
-vds-lsp --wsl-optimize daemon start
-vds-lsp type-check src/
-```
-
-### Batch Operations
-
-```bash
-# Parallel batch with WSL2 optimization
-vds-lsp --wsl-optimize batch-format src/ --apply --jobs 4
-
-# Organize imports
-vds-lsp --wsl-optimize batch-organize-imports src/ --apply
-```
-
-### Navigation
-
-```bash
-# Fast navigation with WSL2 optimization
-vds-lsp --wsl-optimize goto --file "src/app.py:10:5" my_function
-vds-lsp --wsl-optimize refs --file "src/app.py:10:5" my_function
-```
-
-## Windows Integration
-
-### Accessing Files from Windows
-
-When accessing WSL2 files from Windows:
-- Use `\\wsl$\Ubuntu\home\user\projects\...`
-- Avoid drive letters like `C:\`
-- Use WSL2 terminals for development
-
-### VS Code
-
-For best experience:
-- Install VS Code Server in WSL2
-- Use the WSL extension
-- Open workspace from WSL2 terminal
-
-### File Watchers
-
-If using file watchers (e.g., `--watch` mode):
-- Ensure your workspace is in Linux filesystem
-- WSL2 file watching works best on `/home/` paths
-
-```bash
-vds-lsp --wsl-optimize diagnostics src/ --watch
-```
-
-## Performance Comparison
-
-| Configuration | Response Time | Notes |
-|---------------|---------------|-------|
-| Native Linux | ~100ms | Baseline |
-| WSL2 (optimized) | ~150ms | +50ms overhead |
-| WSL2 (not optimized) | ~300ms | +200ms overhead |
-| WSL2 + /mnt/c paths | ~500ms+ | Not recommended |
-
-## See Also
-
-- [Docker Mode](docker-mode.md) - Alternative for Windows users
-- [Parallel Processing](parallel-processing.md) - Performance improvements
-- [Configuration Reference](../reference/configuration.md#platform-settings)