Skip to content

Commit 2a8d4f9

Browse files
HeyItsGilbertHeyItsGilbert
authored
Merge pull request #5 from PSInclusive/copilot/fix-4
Add comprehensive GitHub Copilot instructions for PowerShell Localization extension development
2 parents 9690196 + c0bf032 commit 2a8d4f9

1 file changed

Lines changed: 271 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# PowerShell Localization VS Code Extension
2+
3+
A Visual Studio Code extension that displays PowerShell localization variable values as decorations in your editor, making it easier to develop and debug internationalized PowerShell modules.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
**CRITICAL: NEVER CANCEL ANY BUILD OR TEST COMMANDS. All build times and timeouts have been measured and validated. Builds may take several minutes but will complete successfully if you wait.**
8+
9+
## Working Effectively
10+
11+
### Bootstrap, Build, and Test the Repository
12+
13+
**NEVER CANCEL any of these commands - all have been validated to complete successfully:**
14+
15+
1. **Install dependencies** (takes ~30 seconds):
16+
```bash
17+
yarn install
18+
```
19+
20+
2. **Compile TypeScript** (takes ~3 seconds, NEVER CANCEL - use 60+ second timeout):
21+
```bash
22+
yarn run compile
23+
```
24+
25+
3. **Run linting** (takes ~1 second):
26+
```bash
27+
yarn run lint
28+
```
29+
30+
4. **Install Visual Studio Code Extension manager** (takes ~90 seconds, NEVER CANCEL):
31+
```bash
32+
npm install -g @vscode/vsce
33+
```
34+
35+
5. **Package the extension** (takes ~5 seconds):
36+
```bash
37+
echo 'y' | vsce package --allow-missing-repository
38+
```
39+
40+
6. **Complete build and validation** (total time ~2-3 minutes, NEVER CANCEL - use 300+ second timeout):
41+
```bash
42+
yarn install && yarn run compile && yarn run lint && vsce package --allow-missing-repository
43+
```
44+
45+
### Alternative PowerShell-based Build (Optional)
46+
47+
The repository includes PowerShell-based build scripts, but they require PowerShell Gallery access which may not be available in all environments:
48+
49+
```powershell
50+
# If PowerShell Gallery is available
51+
./build.ps1 -Bootstrap -Task Test
52+
53+
# List available build tasks
54+
./build.ps1 -Help
55+
```
56+
57+
**Note**: In environments without PowerShell Gallery access, use the yarn-based build commands above instead.
58+
59+
### Manual Validation and Testing
60+
61+
**VALIDATION SCENARIOS**: Always run these manual validation steps after making changes:
62+
63+
1. **Test PowerShell localization parsing** (works immediately):
64+
```bash
65+
pwsh -File ./resources/LocalizationParser.ps1 -ModuleFile ./tests/fixtures/Example/Example.psm1 -UICulture en-US -Verbose
66+
```
67+
Should output JSON with `LocalizedData` and `AsSplat` keys containing English values (Key1: "Value1", etc.).
68+
69+
2. **Test French localization parsing** (validate multi-language support):
70+
```bash
71+
pwsh -File ./resources/LocalizationParser.ps1 -ModuleFile ./tests/fixtures/Example/Example.psm1 -UICulture fr-FR
72+
```
73+
Should output JSON with French values (Key1: "Valeur1", etc.).
74+
75+
3. **Verify extension package creation**:
76+
```bash
77+
ls -la *.vsix
78+
```
79+
Should show a `.vsix` file (e.g., `powershelllocalization-0.2.0.vsix`) approximately 225KB in size.
80+
81+
4. **Check compiled output**:
82+
```bash
83+
ls -la out/
84+
```
85+
Should contain 10 compiled JavaScript files including `extension.js`, `extensionManager.js`, `powershellExecutor.js`, etc.
86+
87+
5. **Validate TypeScript compilation produces source maps**:
88+
```bash
89+
ls out/*.js.map | wc -l
90+
```
91+
Should show 10 source map files for debugging support.
92+
93+
6. **Test incremental development workflow**:
94+
```bash
95+
# Make a trivial change
96+
echo "// Test comment" >> src/utils.ts
97+
# Compile and lint
98+
yarn run compile && yarn run lint
99+
# Revert change
100+
git checkout src/utils.ts
101+
```
102+
Should complete without errors and revert cleanly.
103+
104+
### VS Code Testing Limitations
105+
106+
**IMPORTANT**: VS Code extension tests (`yarn run vscode:test`) cannot run in environments without internet access to download VS Code. This is normal and expected. The extension functionality can be validated through:
107+
- Successful compilation and packaging
108+
- Manual testing of the PowerShell localization parser
109+
- Linting validation
110+
- Review of compiled output files
111+
112+
## Development Workflow
113+
114+
### Making Code Changes
115+
116+
1. **Always run the complete build chain first** to ensure starting state is clean
117+
2. **Make your changes** to TypeScript files in `src/`
118+
3. **Compile immediately** after each change: `yarn run compile`
119+
4. **Run linting** to catch issues early: `yarn run lint`
120+
5. **Test the PowerShell parser** if you modify localization logic
121+
6. **Package the extension** to ensure no packaging issues: `vsce package --allow-missing-repository`
122+
123+
### Key Commands for Development
124+
125+
- **Watch mode for continuous compilation**: `yarn run watch`
126+
- **Clean build**: Remove `out/` directory, then run full build
127+
- **Test localization parser**: Use the validated command above with test fixtures
128+
- **Format code**: Follow the existing ESLint configuration
129+
130+
### Common Validation Steps
131+
132+
Before completing any change, always run:
133+
```bash
134+
yarn run lint && yarn run compile && vsce package --allow-missing-repository
135+
```
136+
137+
## Architecture Overview
138+
139+
### Key Projects and Components
140+
141+
1. **Extension Entry Point** (`src/extension.ts`)
142+
- Main VS Code extension activation/deactivation logic
143+
144+
2. **Extension Manager** (`src/extensionManager.ts`)
145+
- Central coordinator for all extension functionality
146+
- Manages component lifecycle and configuration changes
147+
148+
3. **PowerShell Integration** (`src/powershellExecutor.ts`, `resources/LocalizationParser.ps1`)
149+
- Executes PowerShell scripts to parse localization data
150+
- Core functionality for extracting Import-LocalizedData calls
151+
152+
4. **Module Scanner** (`src/moduleScanner.ts`)
153+
- Scans workspace for PowerShell modules (.psm1 files)
154+
- Detects Import-LocalizedData usage patterns
155+
156+
5. **Inline Values Provider** (`src/inlineValuesProvider.ts`)
157+
- Provides inline value display during debugging
158+
- Integrates with VS Code's debugging API
159+
160+
6. **Decoration Provider** (`src/decorationProvider.ts`)
161+
- Shows localization values as editor decorations
162+
- Error Lens style visual feedback
163+
164+
7. **Configuration Manager** (`src/configuration.ts`)
165+
- Handles VS Code extension settings
166+
- Type-safe configuration access
167+
168+
### Test Fixtures Location
169+
170+
- **Example PowerShell module**: `tests/fixtures/Example/Example.psm1`
171+
- **English localization**: `tests/fixtures/Example/en-US/Example.psd1`
172+
- **French localization**: `tests/fixtures/Example/fr-FR/Example.psd1`
173+
174+
These fixtures demonstrate the extension's functionality and can be used for manual testing.
175+
176+
## Build Timing and Expectations
177+
178+
- **Dependency installation** (first time): 30 seconds (NEVER CANCEL, use 120+ second timeout)
179+
- **Dependency installation** (subsequent): <1 second (Already up-to-date)
180+
- **TypeScript compilation**: 2-3 seconds (NEVER CANCEL, use 60+ second timeout)
181+
- **Linting**: 1 second (NEVER CANCEL, use 30+ second timeout)
182+
- **Extension packaging**: 3-5 seconds (NEVER CANCEL, use 60+ second timeout)
183+
- **Complete build chain** (yarn install + compile + lint + package): 7-8 seconds when deps exist
184+
- **Total build time from scratch**: 40-50 seconds including first-time dependency installation
185+
- **vsce installation** (one time): 90 seconds (NEVER CANCEL, use 300+ second timeout)
186+
- **PowerShell localization parsing**: < 1 second (instantaneous)
187+
188+
**All commands have been validated and measured. These timings are accurate for the environment.**
189+
190+
## Troubleshooting
191+
192+
### PowerShell Gallery Not Available
193+
If `./build.ps1 -Bootstrap` fails with PSGallery errors:
194+
- Use yarn-based build commands instead
195+
- This is normal in restricted environments
196+
- All functionality can be validated without PowerShell Gallery modules
197+
198+
### VS Code Tests Cannot Run
199+
If `yarn run vscode:test` fails with network errors:
200+
- This is expected in environments without internet access
201+
- Use manual validation methods described above
202+
- The extension can still be fully built and validated
203+
204+
### Build Failures
205+
If any build command fails:
206+
1. Check Node.js version (requires 18+): `node --version` (verified: v20.19.4 works)
207+
2. Check yarn version: `yarn --version` (verified: 1.22.22 works)
208+
3. Check PowerShell version (requires 7+): `pwsh --version` (verified: 7.4.10 works)
209+
4. Try cleaning: `rm -rf out/ node_modules/ && yarn install`
210+
5. Check for file permission issues in the out/ directory
211+
212+
### Cannot Install vsce
213+
If `npm install -g @vscode/vsce` fails:
214+
- Use yarn instead: `yarn global add @vscode/vsce`
215+
- Check npm permissions or use a different package manager
216+
- Verify network connectivity
217+
218+
### Extension Package Size Issues
219+
If the .vsix file is unexpectedly large or small:
220+
- Expected size: approximately 225KB
221+
- Contains 35 files including compiled JavaScript, documentation, and assets
222+
- Check if out/ directory was compiled correctly before packaging
223+
224+
### PowerShell Script Execution Issues
225+
If the LocalizationParser.ps1 script fails:
226+
- Ensure PowerShell execution policy allows script execution
227+
- Check that the test fixtures exist in tests/fixtures/Example/
228+
- Verify PowerShell 7+ is being used (not Windows PowerShell 5.1)
229+
230+
## Extension Settings
231+
232+
This extension contributes these VS Code settings:
233+
234+
- `powershellLocalization.enableDecorations`: Enable/disable decoration display (default: true)
235+
- `powershellLocalization.enableInlineValues`: Enable/disable inline values during debugging (default: false)
236+
- `powershellLocalization.searchExclude`: Configure glob patterns for excluding directories (default: excludes node_modules, out, dist, .git)
237+
238+
## Common File Locations
239+
240+
### Repository Root
241+
```
242+
├── .github/workflows/ # CI/CD workflows
243+
├── src/ # TypeScript source code
244+
├── out/ # Compiled JavaScript (after build)
245+
├── tests/ # Test files and fixtures
246+
├── resources/ # PowerShell scripts and resources
247+
├── static/ # Images and static assets
248+
├── package.json # Extension manifest and npm config
249+
├── tsconfig.json # TypeScript configuration
250+
├── eslint.config.mjs # Linting configuration
251+
├── build.ps1 # PowerShell build script
252+
├── psake.ps1 # PowerShell build tasks
253+
└── requirements.psd1 # PowerShell module dependencies
254+
```
255+
256+
### Source Code Structure (`src/`)
257+
```
258+
├── extension.ts # Main entry point
259+
├── extensionManager.ts # Central coordinator
260+
├── configuration.ts # Settings management
261+
├── logger.ts # Logging utility
262+
├── moduleScanner.ts # PowerShell module detection
263+
├── powershellExecutor.ts # PowerShell integration
264+
├── inlineValuesProvider.ts # Debug inline values
265+
├── decorationProvider.ts # Editor decorations
266+
├── types.ts # TypeScript definitions
267+
├── utils.ts # Utility functions
268+
└── test/extension.test.ts # VS Code extension tests
269+
```
270+
271+
Always check these key files after making changes to understand the extension's behavior and ensure your modifications integrate properly with the existing architecture.

0 commit comments

Comments
 (0)