Skip to content

Commit 74001e6

Browse files
unknowIfGuestInDreamunknowIfGuestInDream
authored
ci: Improve copilot
1 parent 4074acc commit 74001e6

12 files changed

Lines changed: 2542 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Copilot Instructions for VS Code Extension Development
2+
3+
## Repository Overview
4+
5+
This repository is a **VS Code extension** written in **TypeScript** and built with **esbuild**.
6+
The extension currently focuses on **JavaFX/FXML developer experience** (syntax highlighting,
7+
Scene Builder integration, code navigation, formatting, and outline support for `.fxml` files),
8+
but the patterns and conventions here are broadly reusable across VS Code extension repositories
9+
under the `tlcsdm` organization.
10+
11+
---
12+
13+
## Technology Stack
14+
15+
| Layer | Technology |
16+
|---|---|
17+
| Language | TypeScript (strict) |
18+
| Bundler | esbuild (`esbuild.mjs`) |
19+
| Linter | ESLint + typescript-eslint (`eslint.config.mjs`) |
20+
| Test runner | `@vscode/test-cli` + Mocha (`@vscode/test-electron`) |
21+
| Packaging | `@vscode/vsce` |
22+
| CI | GitHub Actions (`.github/workflows/`) |
23+
| Localization | `package.nls.json` + `package.nls.{locale}.json` |
24+
25+
---
26+
27+
## Project Layout
28+
29+
```
30+
src/ TypeScript source files
31+
extension.ts Entry point — activate() and deactivate()
32+
*.ts Feature modules (providers, utilities)
33+
test/ Mocha test suites (run inside VS Code)
34+
syntaxes/ TextMate grammars (.tmLanguage.json)
35+
images/ Extension icons and assets
36+
dist/ Compiled output (git-ignored)
37+
package.json Extension manifest and contribution points
38+
package.nls.json English localization strings
39+
package.nls.zh-cn.json Simplified Chinese strings
40+
package.nls.ja.json Japanese strings
41+
language-configuration.json Language bracket/comment rules
42+
esbuild.mjs Build script
43+
eslint.config.mjs ESLint configuration
44+
tsconfig.json TypeScript configuration
45+
.github/workflows/ CI workflows (build, test, publish, release)
46+
.github/skills/ Reusable Copilot skill guides (see below)
47+
```
48+
49+
---
50+
51+
## Coordinated Change Rule
52+
53+
> **Whenever you change extension behavior, update ALL of the following that are affected:**
54+
>
55+
> 1. `src/` — TypeScript implementation
56+
> 2. `package.json` — contribution points (commands, configuration, menus, languages, grammars)
57+
> 3. `package.nls.json` — English localization keys/values
58+
> 4. `package.nls.zh-cn.json` and other locale files — translated values
59+
> 5. `README.md` — user-facing documentation
60+
> 6. `CHANGELOG.md` — release notes entry
61+
> 7. `src/test/` — unit/integration tests
62+
63+
Failing to keep these in sync is the most common source of bugs and broken releases.
64+
65+
---
66+
67+
## Development Workflows
68+
69+
```bash
70+
# Install dependencies
71+
npm install
72+
73+
# Type-check without emitting (fast feedback)
74+
npm run check-types
75+
76+
# Compile for development
77+
npm run compile
78+
79+
# Watch mode
80+
npm run watch
81+
82+
# Lint
83+
npm run lint
84+
85+
# Run tests (requires a display / VS Code instance)
86+
npm run test
87+
88+
# Production bundle (minified, no source maps)
89+
npm run package
90+
91+
# Package as .vsix
92+
npx @vscode/vsce package
93+
```
94+
95+
---
96+
97+
## Coding Conventions
98+
99+
### TypeScript
100+
- All files use **strict TypeScript** (`tsconfig.json` enforces this).
101+
- Prefer `const` and `readonly`; avoid `any`.
102+
- Use `vscode.ExtensionContext.subscriptions.push(...)` for all disposables registered in `activate()`.
103+
- Never store global mutable state; thread context through function parameters or classes.
104+
- Export only what is needed by other modules; keep internals `private` or unexported.
105+
106+
### Naming
107+
- Commands: `<publisher>.<extensionName>.<verb><Object>` — e.g., `tlcsdm.javafxSupport.openInSceneBuilder`
108+
- Configuration keys: `<publisher>.<extensionName>.<section>.<key>` — e.g., `tlcsdm.javafxSupport.sceneBuilderPath`
109+
- TypeScript classes: `PascalCase`; functions and variables: `camelCase`
110+
111+
### Error Handling
112+
- Surface errors to users via `vscode.window.showErrorMessage(...)`, not bare `console.error`.
113+
- Use `vscode.window.showWarningMessage(...)` for recoverable issues.
114+
- Catch and handle promise rejections; do not let unhandled rejections crash the extension host.
115+
116+
### Localization
117+
- Every user-facing string in `package.json` must use a `%key%` placeholder.
118+
- The key must exist in `package.nls.json` (English), and a best-effort translation in every other locale file.
119+
- Strings inside TypeScript source are currently inline; use `vscode.l10n.t(...)` for new strings if i18n is needed in code.
120+
121+
### Provider Pattern
122+
- Implement VS Code provider interfaces (`vscode.DefinitionProvider`, `vscode.DocumentSymbolProvider`, etc.) as named classes in dedicated files.
123+
- Register providers in `activate()` via `context.subscriptions.push(vscode.languages.register*(...))`.
124+
- Keep provider logic pure and testable; avoid side effects in provider methods.
125+
126+
### Menus and When-Clauses
127+
- Use the narrowest `when` clause possible for menu contributions.
128+
- Prefer built-in context keys (`resourceLangId`, `editorLangId`) over custom context keys where sufficient.
129+
130+
### Commit Messages
131+
- Follow the **Angular commit convention** for all commits.
132+
- Use the format: `<type>(<scope>): <subject>` when a scope is helpful, or `<type>: <subject>` when it is not.
133+
- Prefer common types such as `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, `style` and `chore`.
134+
- Keep the subject concise, imperative, and lowercase where practical.
135+
- Examples:
136+
- `feat(fxml): add controller navigation`
137+
- `fix(scene-builder): handle missing executable path`
138+
- `docs(copilot): add vscode extension skill guidance`
139+
140+
---
141+
142+
## Extension Activation
143+
144+
- `activationEvents` in `package.json` controls when the extension loads.
145+
- Prefer `onLanguage:<id>` events over `*` (eager activation) to reduce startup impact.
146+
- Keep `activate()` fast: defer expensive work (file system scans, network calls) using lazy initialization or `onDidOpenTextDocument`.
147+
148+
---
149+
150+
## Security Considerations
151+
152+
- Never execute untrusted user input as shell commands without validation and escaping.
153+
- When spawning child processes (e.g., launching Scene Builder), sanitize all path arguments.
154+
- Do not write to arbitrary file system paths based on user or workspace input without confirmation.
155+
- Avoid `eval` and dynamic `require` inside the extension bundle.
156+
157+
---
158+
159+
## Skills Reference
160+
161+
Detailed, reusable guides are in `.github/skills/`. Consult them when working on these areas:
162+
163+
| Topic | File |
164+
|---|---|
165+
| Extension architecture & patterns | `.github/skills/vscode-extension-architecture/SKILL.md` |
166+
| `package.json` contribution points | `.github/skills/vscode-package-json-and-contributes/SKILL.md` |
167+
| Commands & activation | `.github/skills/vscode-commands-and-activation/SKILL.md` |
168+
| Language features & providers | `.github/skills/vscode-language-features/SKILL.md` |
169+
| Webviews & native VS Code UI | `.github/skills/vscode-webview-and-ui/SKILL.md` |
170+
| Configuration & settings | `.github/skills/vscode-configuration-and-settings/SKILL.md` |
171+
| Testing & debugging | `.github/skills/vscode-testing-and-debugging/SKILL.md` |
172+
| Build, packaging & release | `.github/skills/vscode-build-package-and-release/SKILL.md` |
173+
| i18n & documentation | `.github/skills/vscode-i18n-and-docs/SKILL.md` |
174+
| Performance & compatibility | `.github/skills/vscode-performance-and-compatibility/SKILL.md` |
175+
| Refactoring & maintenance | `.github/skills/vscode-refactor-and-maintenance/SKILL.md` |

‎.github/skills/vscode-build-package-and-release/SKILL.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
name: vscode-build-package-and-release
3+
description: Guidance for building, packaging, and releasing VS Code extensions with esbuild, vsce, and GitHub Actions workflows.
4+
---
5+
6+
# Skill: Build, Packaging, and Release
7+
8+
## Overview
9+
10+
This project uses **esbuild** for fast TypeScript bundling and **`@vscode/vsce`** for creating
11+
and publishing `.vsix` packages. GitHub Actions automate the CI, release tagging, and Marketplace
12+
publish workflows.
13+
14+
---
15+
16+
## Build Scripts
17+
18+
```jsonc
19+
// package.json scripts
20+
"vscode:prepublish": "npm run package",
21+
"compile": "npm run check-types && node esbuild.mjs",
22+
"check-types": "tsc --noEmit",
23+
"watch": "node esbuild.mjs --watch",
24+
"package": "npm run check-types && node esbuild.mjs --production",
25+
"pretest": "tsc -p ./ && npm run lint",
26+
"lint": "eslint src",
27+
"test": "vscode-test --config ./.vscode-test.json"
28+
```
29+
30+
| Command | Purpose |
31+
|---|---|
32+
| `npm run compile` | Type-check + bundle (dev, with source maps) |
33+
| `npm run check-types` | Type-check only, no emit |
34+
| `npm run watch` | Incremental rebuild on file change |
35+
| `npm run package` | Production bundle (minified, no source maps) |
36+
| `npm run lint` | ESLint over `src/` |
37+
| `npm run test` | Full test run (requires display) |
38+
| `npx @vscode/vsce package` | Create `.vsix` artifact |
39+
40+
---
41+
42+
## esbuild Configuration (`esbuild.mjs`)
43+
44+
Key settings for VS Code extensions:
45+
46+
```javascript
47+
await esbuild.build({
48+
entryPoints: ['src/extension.ts'],
49+
bundle: true,
50+
format: 'cjs', // CommonJS — required by VS Code extension host
51+
platform: 'node', // Node.js environment
52+
external: ['vscode'], // MUST be external — provided by VS Code at runtime
53+
outfile: 'dist/extension.js',
54+
minify: production, // true for --production flag
55+
sourcemap: !production,
56+
sourcesContent: false, // don't embed source content in maps (reduces size)
57+
logLevel: 'silent',
58+
});
59+
```
60+
61+
**Important:** `vscode` must always be in `external`. If you add new `external` dependencies,
62+
add them here (e.g., `external: ['vscode', 'electron']`).
63+
64+
For native Node.js modules (e.g., `.node` binaries), also mark them external and
65+
copy them to `dist/` with a post-build script.
66+
67+
---
68+
69+
## `.vscodeignore`
70+
71+
Controls what is excluded from the `.vsix` package. Always exclude:
72+
73+
```
74+
.vscode/**
75+
.github/**
76+
src/**
77+
out/**
78+
node_modules/**
79+
*.map
80+
esbuild.mjs
81+
tsconfig.json
82+
eslint.config.mjs
83+
.vscode-test.json
84+
```
85+
86+
Keep the package small: only ship `dist/`, `syntaxes/`, `images/`, `language-configuration.json`,
87+
`package.json`, `package.nls*.json`, `README.md`, `CHANGELOG.md`, and `LICENSE`.
88+
89+
---
90+
91+
## Versioning
92+
93+
Follow [Semantic Versioning](https://semver.org/):
94+
95+
| Change type | Version bump |
96+
|---|---|
97+
| Bug fixes only | Patch (`1.0.3` → `1.0.4`) |
98+
| New backward-compatible features | Minor (`1.0.3` → `1.1.0`) |
99+
| Breaking changes | Major (`1.0.3` → `2.0.0`) |
100+
101+
Update `version` in `package.json` and add a `CHANGELOG.md` entry before tagging.
102+
103+
---
104+
105+
## GitHub Actions Workflows
106+
107+
### Typical Workflow Structure
108+
109+
```
110+
.github/workflows/
111+
build.yml Compile + lint + test on every PR and push
112+
artifact.yml Build and upload .vsix artifact
113+
release.yml Create GitHub Release on tag push
114+
publish.yml Publish to VS Code Marketplace
115+
sync-gitee.yml Mirror to Gitee
116+
sync-vscode-engine.yml Keep engines.vscode up to date
117+
```
118+
119+
### Example: `build.yml`
120+
121+
```yaml
122+
name: Build
123+
124+
on:
125+
push:
126+
branches: [master]
127+
pull_request:
128+
branches: [master]
129+
130+
jobs:
131+
build:
132+
runs-on: ubuntu-latest
133+
steps:
134+
- uses: actions/checkout@v4
135+
- uses: actions/setup-node@v4
136+
with:
137+
node-version: '22.x'
138+
cache: 'npm'
139+
- run: npm ci
140+
- run: npm run compile
141+
- run: npm run lint
142+
- name: Run tests
143+
run: xvfb-run -a npm run test
144+
```
145+
146+
### Example: `publish.yml` (Marketplace)
147+
148+
```yaml
149+
name: Publish
150+
151+
on:
152+
release:
153+
types: [published]
154+
155+
jobs:
156+
publish:
157+
runs-on: ubuntu-latest
158+
steps:
159+
- uses: actions/checkout@v4
160+
- uses: actions/setup-node@v4
161+
with:
162+
node-version: '22.x'
163+
cache: 'npm'
164+
- run: npm ci
165+
- run: npm run package
166+
- run: npx @vscode/vsce publish -p ${{ secrets.VSCE_PAT }}
167+
# Optionally also publish to Open VSX
168+
- run: npx ovsx publish -p ${{ secrets.OVSX_PAT }}
169+
```
170+
171+
---
172+
173+
## Release Checklist
174+
175+
- [ ] `version` in `package.json` is bumped appropriately.
176+
- [ ] `CHANGELOG.md` has a new entry with date and version.
177+
- [ ] `README.md` is up to date.
178+
- [ ] All locale files (`package.nls*.json`) reflect any new keys.
179+
- [ ] `npm run compile` passes.
180+
- [ ] `npm run lint` passes.
181+
- [ ] Tests pass locally and in CI.
182+
- [ ] `.vsix` package is smoke-tested by installing it in VS Code.
183+
- [ ] GitHub Release created with the tag `v<version>`.
184+
- [ ] Marketplace publish succeeds.
185+
186+
---
187+
188+
## Dependency Management
189+
190+
- Use `npm ci` (not `npm install`) in CI to get reproducible installs from `package-lock.json`.
191+
- The `overrides` field in `package.json` can force transitive dependency versions to address security vulnerabilities.
192+
- Keep `@types/vscode` version aligned with `engines.vscode` minimum version.
193+
- Run `npx @vscode/vsce ls` to see what will be packaged before publishing.
194+
195+
---
196+
197+
## References
198+
199+
- [Publishing Extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
200+
- [Bundling Extensions](https://code.visualstudio.com/api/working-with-extensions/bundling-extension)
201+
- [@vscode/vsce](https://github.com/microsoft/vscode-vsce)
202+
- [Continuous Integration](https://code.visualstudio.com/api/working-with-extensions/continuous-integration)

0 commit comments

Comments
 (0)