|
| 1 | +# Copilot Project Instructions (vscode-ecl) |
| 2 | + |
| 3 | +These instructions give AI coding agents the minimum project-specific context needed to be productive. Keep answers concise, reference concrete files, and follow existing patterns. |
| 4 | + |
| 5 | +## 1. Project Purpose & Top-Level Architecture |
| 6 | + |
| 7 | +VS Code extension providing HPCC Systems ECL/KEL/Dashy language + notebook + platform workflow support. Core responsibilities: |
| 8 | + |
| 9 | +- Language support (syntax, syntax checking, snippets, record definition insertion) |
| 10 | +- Workunit submission & monitoring against HPCC Platform clusters |
| 11 | +- KEL -> ECL generation workflow |
| 12 | +- ECL Notebook (.eclnb) execution + custom renderers (Workunit + ObservableJS) |
| 13 | +- Auxiliary dashboard / ECL Watch webview UI |
| 14 | + |
| 15 | +Architecture overview: |
| 16 | + |
| 17 | +- Entry points: `src/extension.ts` (Node runtime), `src/web-extension.ts` (browser/web). Both dynamically import feature modules after localization init. |
| 18 | +- Feature modules (lazy loaded): `src/ecl/`, `src/kel/`, `src/notebook/`, optional `dashy/` (currently commented in extension.ts) plus UI components in `src/eclwatch.tsx`. |
| 19 | +- Build outputs to `dist/` (extension + web renderers) and `dist-util/` (docs vector DB generator) via `esbuild.mjs`. |
| 20 | +- Grammar + syntax: `ecl-tmLanguage/`, `syntaxes/kel.tmLanguage.json`, `syntaxes/dashy.tmLanguage.json`. |
| 21 | +- Internationalization: strings resolved through `./util/localize` and `nls` JSON generation (`npm run gen-nls`). |
| 22 | + |
| 23 | +## 2. Build & Dev Workflow |
| 24 | + |
| 25 | +Primary scripts (`package.json`): |
| 26 | + |
| 27 | +- Type generation (watch): `npm run gen-node-watch`, `npm run gen-webview-watch` (tsc emit d.ts only per config). |
| 28 | +- Bundle dev watch (all): run VS Code build task (maps to `build` task which depends on `gen-node-watch`, `gen-webview-watch`, `build-ts-watch`). |
| 29 | +- One-off production build: `npm run build` (runs `gen-types` + `build-ts`). |
| 30 | +- Lint: `npm run lint` / auto-fix: `npm run lint-fix`. |
| 31 | +- Testing: `npm run test:vitest` (watch), `npm run test:vitest-run` (once), `npm run test:vitest-ui` (with UI), `npm run test:vitest-coverage` (with coverage). |
| 32 | +- Package VSIX: `npm run package` (output `ecl.vsix`). |
| 33 | +- Publish (requires auth): `npm run publish`. |
| 34 | +- Generate localized resources: `npm run gen-nls` then `npm run merge-nls` if needed. |
| 35 | +- Vector doc index (LLM prompt support): `npm run gen-docs-vecdb` (writes `dist/docs.vecdb`). |
| 36 | + |
| 37 | +Typical dev loop: |
| 38 | + |
| 39 | +1. Run default build task (Ctrl+Shift+B) for watch mode. |
| 40 | +2. Launch extension host (F5). Open an `.ecl` or `.kel` file to trigger activation. |
| 41 | +3. Modify sources under `src/`; esbuild watch rebuilds to `dist/` automatically. |
| 42 | + |
| 43 | +## 3. Key Extension Contributions (from `package.json`) |
| 44 | + |
| 45 | +- Languages: ECL (`.ecl`, `.mod`, `.ecllib`), KEL (`.kel`), Dashy (`.dashy` JSON injection grammar). |
| 46 | +- Commands & menus are heavily context-driven (see `package.json` for enablement). Do not hardcode strings—reuse existing command IDs. |
| 47 | +- Notebooks: id `ecl-notebook`; renderers `wuRenderer` (Workunit JSON) and `ojsRenderer` (ObservableJS cells). |
| 48 | +- Debugger type: `ecl` (program `dist/debugger.js`) with launch schema documented in README. |
| 49 | +- Chat participant: `chat.ecl` —prefer expanding these via contributes if adding capabilities. |
| 50 | + |
| 51 | +## 4. Source Layout & Patterns |
| 52 | + |
| 53 | +- Dynamic imports keep activation fast; new feature areas should follow pattern in `extension.ts` (lazy import after `initialize()`). |
| 54 | +- Prefer colocated feature folders: `src/<domain>/main.ts|js` exporting `activate(context)` consumed by entry point. |
| 55 | +- Webview / browser-targeted code uses `tsconfig.webview.json` (ESM / browser target) vs Node code using root `tsconfig.json` (CJS target). Match platform when adding entrypoints. |
| 56 | +- React (v17) used for complex UI (`eclwatch.tsx`, notebook renderers). Use function components + hooks; avoid introducing different UI libs. |
| 57 | +- Telemetry encapsulated in `src/telemetry/`; send only via exported `reporter` to keep consistency. |
| 58 | +- **Prefer VS Code APIs over Node.js APIs**: Use `vscode.workspace.fs` for file operations, `vscode.Uri` for paths, and VS Code's built-in utilities where available. This ensures better integration with the VS Code environment, proper workspace context, and compatibility with both Node and web environments. |
| 59 | + |
| 60 | +## 5. Localization & Strings |
| 61 | + |
| 62 | +- New user-facing strings should use localization pipeline: add to base `package.nls.json`, run `npm run gen-nls` (creates `lib-util/generate.js` output consumed) then reconcile missing entries under `tmp/package.nls.*.missing.json` before commit. |
| 63 | +- Avoid embedding raw UI strings directly in TSX—centralize when reused or visible. |
| 64 | + |
| 65 | +## 6. HPCC Platform Integration |
| 66 | + |
| 67 | +- Workunit operations & platform APIs housed under `src/hpccplatform/` and supporting util modules (look for submission, polling, and tree view providers). Follow existing async patterns (Promise-based, minimal global state, use VS Code `TreeDataProvider`). |
| 68 | +- Submission UI flows rely on status bar selections (launch config + target cluster) + tree updates; keep side effects isolated. |
| 69 | + |
| 70 | +## 7. Notebooks & Renderers |
| 71 | + |
| 72 | +- Notebook kernel / controller logic under `src/notebook/` (activation imported in both node + web builds). |
| 73 | +- Renderer isolation: each renderer is a separate esbuild entry (see `esbuild.mjs`). Add new renderer by adding another `main(tsconfigBrowser, entry, "browser", format)` call and corresponding `notebookRenderer` contribution. |
| 74 | + |
| 75 | +## 8. Adding Features Safely |
| 76 | + |
| 77 | +- Reuse existing command categories (`ECL`, `KEL`) and enablement contexts (e.g. `ecl.connected`). |
| 78 | +- Extend menus via existing submenus `setState`, `setPriority` when dealing with workunits rather than creating new ones. |
| 79 | +- For network/platform code, respect existing configuration settings (e.g. proxy, `rejectUnauthorized`). |
| 80 | + |
| 81 | +## 9. Testing & Quality |
| 82 | + |
| 83 | +- **Vitest** is now configured as the primary testing framework (`vitest.config.ts`). Legacy mocha tests remain in `test/` but are excluded from vitest runs. |
| 84 | +- New tests should be placed in `src/__tests__/` using `*.test.ts` or `*.spec.ts` naming convention. |
| 85 | +- Available vitest commands: |
| 86 | + - `npm run test:vitest` - Run tests in watch mode |
| 87 | + - `npm run test:vitest-run` - Run tests once |
| 88 | + - `npm run test:vitest-ui` - Run tests with UI |
| 89 | + - `npm run test:vitest-coverage` - Run tests with coverage report |
| 90 | +- Vitest config includes jsdom environment, global test functions (`describe`, `it`, `expect`), and coverage reporting. |
| 91 | +- Keep new logic unit-testable (pure functions in util modules). Avoid coupling VS Code API calls inside deep logic—wrap them. |
| 92 | +- See `src/__tests__/vitest-example.test.ts` for testing patterns including mocks, timers, DOM manipulation, and async operations. |
| 93 | + |
| 94 | +## 10. Bundling Constraints |
| 95 | + |
| 96 | +- External modules declared in `esbuild.mjs` (e.g. `vscode`, core node modules) must remain external. When introducing node-only deps ensure they aren’t required by browser bundles. |
| 97 | +- Browser targets must avoid Node APIs unless polyfilled (current config doesn’t inject shims). |
| 98 | + |
| 99 | +## 11. Vector Doc Index |
| 100 | + |
| 101 | +- File `util/docs.vecdb` copied into `dist/docs.vecdb` for LLM/assistant usage. Updating generation logic: edit `util/index-docs.ts`, rebuild with production flag or run `node dist-util/index-docs.mjs` via script. |
| 102 | + |
| 103 | +## 12. Versioning & Packaging |
| 104 | + |
| 105 | +- Extension version in `package.json`—increment appropriately; run `npm run package` to produce `ecl.vsix`. Publishing uses `vsce publish` (ensure changelog updated). |
| 106 | + |
| 107 | +## 13. Common Pitfalls |
| 108 | + |
| 109 | +- Forgetting lazy import => increases activation time (avoid exporting heavy modules directly from entry point). |
| 110 | +- Mixing web + node code (ensure correct tsconfig target and esbuild platform entry). |
| 111 | +- Adding untranslated strings (will produce missing locale JSON files under `tmp/`). |
| 112 | + |
| 113 | +When responding, cite file paths (e.g. `src/extension.ts`) and align with these established patterns. If uncertain, inspect `package.json` contributions first. |
| 114 | + |
| 115 | +## 14. VS Code API Reference Shortcuts |
| 116 | + |
| 117 | +Use official docs for API details; below are the most relevant entry points for this project’s common tasks: |
| 118 | + |
| 119 | +- Extension Manifest (`package.json` contributes): https://code.visualstudio.com/api/references/contribution-points |
| 120 | +- Core VS Code API (activation, commands, TreeDataProvider, status bar): https://code.visualstudio.com/api/references/vscode-api |
| 121 | +- Debug Adapter & Debugger contributions (used for `type: "ecl"`): https://code.visualstudio.com/api/extension-guides/debugger-extension |
| 122 | +- Notebook API (controller, renderers): https://code.visualstudio.com/api/extension-guides/notebook |
| 123 | +- Webview UI (used by `eclwatch.tsx` and potential Dashy views): https://code.visualstudio.com/api/extension-guides/webview |
| 124 | +- Localization (NLS): https://code.visualstudio.com/api/advanced-topics/localization |
| 125 | + |
| 126 | +How to apply: |
| 127 | + |
| 128 | +- Before adding a new contribution, confirm an existing pattern in `package.json` (e.g. replicate a command object, adjust `enablement`). |
| 129 | +- For a new Tree View / data provider, follow existing HPCC platform tree patterns under `src/hpccplatform/` and reference TreeDataProvider docs. |
| 130 | +- For new notebook renderer: add entry in `esbuild.mjs` (browser target) + `notebookRenderer` contribution + MIME type contract. |
| 131 | +- For status bar interactions replicate existing approach (search for usages setting `ecl.launchConfiguration` & `ecl.targetCluster`). |
| 132 | + |
| 133 | +When unsure of an API surface (e.g. `WorkspaceEdit`, `TextDocumentContentProvider`, etc.) prefer stable APIs listed in the vscode-api reference; avoid proposed APIs unless already adopted in this repo. |
| 134 | + |
| 135 | +## 15. Reference Sample Extensions |
| 136 | + |
| 137 | +For additional concrete, minimal examples of specific VS Code features (debug adapters, notebooks, webviews, tree views, authentication, testing, etc.), consult the official extension samples repository: |
| 138 | + |
| 139 | +https://github.com/microsoft/vscode-extension-samples |
| 140 | + |
| 141 | +Use these samples to validate API usage patterns before introducing new dependencies. Align any adopted patterns with this project's existing conventions (lazy dynamic imports in `src/extension.ts`, localization via `package.nls.json`, separation of Node vs browser bundles, and avoiding proposed APIs unless already in use). |
0 commit comments