|
| 1 | +# Canonical Path Resolution Test Fixture |
| 2 | + |
| 3 | +This test fixture provides a realistic monorepo environment for testing Paths-LE's canonical path resolution features, including symlink handling and workspace-relative path resolution. |
| 4 | + |
| 5 | +## 🏗️ Structure |
| 6 | + |
| 7 | +``` |
| 8 | +test-fixtures/monorepo-test/ |
| 9 | +├── workspace.code-workspace # VS Code multi-root workspace |
| 10 | +├── setup-symlinks.sh # Script to create symlinks |
| 11 | +├── packages/ |
| 12 | +│ ├── frontend/ |
| 13 | +│ │ ├── src/ |
| 14 | +│ │ │ ├── main.js # Cross-package imports |
| 15 | +│ │ │ ├── symlink-test.js # Symlink references |
| 16 | +│ │ │ ├── utils-link.js # → ../../shared/src/utils.js |
| 17 | +│ │ │ ├── regular-file.js # Regular file for comparison |
| 18 | +│ │ │ └── config.json # Local config file |
| 19 | +│ │ ├── webpack-link.js # → ../../../tools/build-scripts/webpack.config.js |
| 20 | +│ │ ├── shared-link/ # → ../shared (directory symlink) |
| 21 | +│ │ └── normal-file.js # Regular file |
| 22 | +│ ├── backend/ |
| 23 | +│ │ └── src/ |
| 24 | +│ │ └── api.js # Backend API with shared imports |
| 25 | +│ └── shared/ |
| 26 | +│ └── src/ |
| 27 | +│ ├── utils.js # Shared utilities |
| 28 | +│ └── helpers.js # Additional shared code |
| 29 | +└── tools/ |
| 30 | + └── build-scripts/ |
| 31 | + └── webpack.config.js # Build configuration |
| 32 | +``` |
| 33 | + |
| 34 | +## 🚀 Quick Start |
| 35 | + |
| 36 | +### 1. Setup Symlinks |
| 37 | + |
| 38 | +```bash |
| 39 | +cd test-fixtures/monorepo-test |
| 40 | +./setup-symlinks.sh |
| 41 | +``` |
| 42 | + |
| 43 | +### 2. Open in VS Code |
| 44 | + |
| 45 | +```bash |
| 46 | +code workspace.code-workspace |
| 47 | +``` |
| 48 | + |
| 49 | +### 3. Test Canonical Resolution |
| 50 | + |
| 51 | +1. **Install the extension** (if not already installed): |
| 52 | + ```bash |
| 53 | + cd ../../ # Back to paths-le root |
| 54 | + code --install-extension release/paths-le-1.6.0.vsix |
| 55 | + ``` |
| 56 | + |
| 57 | +2. **Open test files** and run `Paths-LE: Extract Paths` (Cmd+Alt+P): |
| 58 | + - `packages/frontend/src/main.js` - Cross-package imports |
| 59 | + - `packages/frontend/src/symlink-test.js` - Symlink references |
| 60 | + |
| 61 | +## 🧪 Test Scenarios |
| 62 | + |
| 63 | +### Scenario A: Cross-Package Imports |
| 64 | +**File**: `packages/frontend/src/main.js` |
| 65 | + |
| 66 | +**Test**: Extract paths from cross-package imports |
| 67 | +```javascript |
| 68 | +import { utils } from '../../shared/src/utils.js'; |
| 69 | +import { api } from '../../../packages/backend/src/api.js'; |
| 70 | +``` |
| 71 | + |
| 72 | +**Expected Results**: |
| 73 | +- With canonical resolution: Resolves relative to correct workspace folders |
| 74 | +- Should handle complex relative paths across package boundaries |
| 75 | + |
| 76 | +### Scenario B: Symlink Resolution |
| 77 | +**File**: `packages/frontend/src/symlink-test.js` |
| 78 | + |
| 79 | +**Test**: Extract paths that go through symlinks |
| 80 | +```javascript |
| 81 | +import utils from './utils-link.js'; // Symlink to ../../shared/src/utils.js |
| 82 | +``` |
| 83 | + |
| 84 | +**Expected Results**: |
| 85 | +- `resolveSymlinks: true` → Shows canonical path to actual file |
| 86 | +- `resolveSymlinks: false` → Shows symlink path as-is |
| 87 | + |
| 88 | +### Scenario C: Directory Symlinks |
| 89 | +**File**: `packages/frontend/src/symlink-test.js` |
| 90 | + |
| 91 | +**Test**: Import through symlinked directory |
| 92 | +```javascript |
| 93 | +import shared from '../shared-link/src/helpers.js'; // Via directory symlink |
| 94 | +``` |
| 95 | + |
| 96 | +**Expected Results**: |
| 97 | +- Should resolve through the symlinked directory to actual file |
| 98 | + |
| 99 | +### Scenario D: Workspace-Relative Paths |
| 100 | +**File**: `packages/frontend/src/main.js` |
| 101 | + |
| 102 | +**Test**: Workspace-relative path references |
| 103 | +```javascript |
| 104 | +const sharedUtil = 'packages/shared/src/helpers.js'; |
| 105 | +``` |
| 106 | + |
| 107 | +**Expected Results**: |
| 108 | +- With workspace resolution: Resolves relative to workspace root |
| 109 | +- Should work correctly in multi-root workspace environment |
| 110 | + |
| 111 | +## ⚙️ Configuration Testing |
| 112 | + |
| 113 | +### Test Configuration A: Full Canonical Resolution |
| 114 | +```json |
| 115 | +{ |
| 116 | + "paths-le.resolution.resolveSymlinks": true, |
| 117 | + "paths-le.resolution.resolveWorkspaceRelative": true |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +### Test Configuration B: Symlinks Only |
| 122 | +```json |
| 123 | +{ |
| 124 | + "paths-le.resolution.resolveSymlinks": true, |
| 125 | + "paths-le.resolution.resolveWorkspaceRelative": false |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +### Test Configuration C: Workspace Only |
| 130 | +```json |
| 131 | +{ |
| 132 | + "paths-le.resolution.resolveSymlinks": false, |
| 133 | + "paths-le.resolution.resolveWorkspaceRelative": true |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +### Test Configuration D: Traditional Mode |
| 138 | +```json |
| 139 | +{ |
| 140 | + "paths-le.resolution.resolveSymlinks": false, |
| 141 | + "paths-le.resolution.resolveWorkspaceRelative": false |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +## 🔍 What to Verify |
| 146 | + |
| 147 | +### ✅ Symlink Resolution |
| 148 | +1. **File symlinks**: `utils-link.js` → `../../shared/src/utils.js` |
| 149 | +2. **Directory symlinks**: `shared-link/` → `../shared/` |
| 150 | +3. **Nested symlinks**: Paths through symlinked directories |
| 151 | + |
| 152 | +### ✅ Workspace Resolution |
| 153 | +1. **Multi-root workspace**: Each package as separate workspace folder |
| 154 | +2. **Cross-package references**: Imports between frontend/backend/shared |
| 155 | +3. **Relative path handling**: Complex `../../` paths across packages |
| 156 | + |
| 157 | +### ✅ Error Handling |
| 158 | +1. **Broken symlinks**: Create and test broken symlinks |
| 159 | +2. **Permission errors**: Test with restricted permissions |
| 160 | +3. **Non-existent paths**: References to missing files |
| 161 | + |
| 162 | +### ✅ Performance |
| 163 | +1. **Caching**: Extract same paths multiple times (should be faster on repeat) |
| 164 | +2. **Large files**: Test with files containing many path references |
| 165 | +3. **Deep nesting**: Complex directory structures |
| 166 | + |
| 167 | +## 🛠️ Manual Testing Steps |
| 168 | + |
| 169 | +### Step 1: Basic Functionality |
| 170 | +```bash |
| 171 | +# 1. Open the workspace |
| 172 | +code test-fixtures/monorepo-test/workspace.code-workspace |
| 173 | + |
| 174 | +# 2. Open a test file |
| 175 | +# File: packages/frontend/src/main.js |
| 176 | + |
| 177 | +# 3. Run extraction |
| 178 | +# Cmd+Alt+P (or Ctrl+Alt+P on Windows/Linux) |
| 179 | +``` |
| 180 | + |
| 181 | +### Step 2: Compare Resolution Modes |
| 182 | +1. Enable canonical resolution in VS Code settings |
| 183 | +2. Extract paths → Note results |
| 184 | +3. Disable canonical resolution in settings |
| 185 | +4. Extract paths → Compare results |
| 186 | + |
| 187 | +### Step 3: Symlink-Specific Test |
| 188 | +1. Open `packages/frontend/src/symlink-test.js` |
| 189 | +2. Extract paths with canonical resolution ON |
| 190 | +3. Should see resolved symlink targets |
| 191 | +4. Extract paths with canonical resolution OFF |
| 192 | +5. Should see symlink paths as-is |
| 193 | + |
| 194 | +## 🐛 Expected Behaviors |
| 195 | + |
| 196 | +### ✅ Success Cases |
| 197 | +- Symlinks resolve to canonical paths when enabled |
| 198 | +- Cross-package imports work correctly in multi-root workspace |
| 199 | +- Performance remains fast with LRU caching |
| 200 | +- Graceful fallback on resolution errors |
| 201 | + |
| 202 | +### ⚠️ Edge Cases |
| 203 | +- Broken symlinks → Use original path |
| 204 | +- Circular symlinks → Detect and handle gracefully |
| 205 | +- Permission denied → Fallback to original path |
| 206 | +- Virtual workspaces → Auto-detect and use traditional resolution |
| 207 | + |
| 208 | +## 🔧 Troubleshooting |
| 209 | + |
| 210 | +### Symlinks Not Working? |
| 211 | +```bash |
| 212 | +# Recreate symlinks |
| 213 | +cd test-fixtures/monorepo-test |
| 214 | +./setup-symlinks.sh |
| 215 | +``` |
| 216 | + |
| 217 | +### VS Code Not Recognizing Workspace? |
| 218 | +- Ensure you opened `workspace.code-workspace` file |
| 219 | +- Check that all workspace folders exist |
| 220 | +- Reload VS Code window |
| 221 | + |
| 222 | +### Extension Not Working? |
| 223 | +```bash |
| 224 | +# Reinstall extension |
| 225 | +cd ../../ # Back to paths-le root |
| 226 | +code --install-extension release/paths-le-1.6.0.vsix --force |
| 227 | +``` |
| 228 | + |
| 229 | +### Debug Information |
| 230 | +1. Enable telemetry: `"paths-le.telemetryEnabled": true` |
| 231 | +2. Open VS Code Developer Tools (Help → Toggle Developer Tools) |
| 232 | +3. Check console for Paths-LE logs |
| 233 | + |
| 234 | +## 📊 Performance Testing |
| 235 | + |
| 236 | +### Create Large Test File |
| 237 | +```bash |
| 238 | +cd test-fixtures/monorepo-test |
| 239 | +node -e " |
| 240 | +const fs = require('fs'); |
| 241 | +const paths = []; |
| 242 | +for(let i = 0; i < 10000; i++) { |
| 243 | + paths.push(\`import file\${i} from './path/to/file\${i}.js';\`); |
| 244 | +} |
| 245 | +fs.writeFileSync('packages/frontend/src/large-test.js', paths.join('\\n')); |
| 246 | +" |
| 247 | +``` |
| 248 | + |
| 249 | +### Test Extraction Performance |
| 250 | +- Should complete in < 1 second with caching |
| 251 | +- Second extraction should be faster (cache hit) |
| 252 | + |
| 253 | +## 🎯 Success Criteria |
| 254 | + |
| 255 | +- ✅ All symlinks resolve correctly when canonical resolution is enabled |
| 256 | +- ✅ Cross-package imports work in multi-root workspace |
| 257 | +- ✅ Configuration toggles work as expected |
| 258 | +- ✅ Performance remains acceptable (< 1s for large files) |
| 259 | +- ✅ Graceful fallback on any resolution errors |
| 260 | +- ✅ Backward compatibility maintained |
0 commit comments