feat(test): add end-to-end tests and harness

.github/workflows/node.js.yml

@@ -29,3 +29,15 @@ jobs:
     - run: npm ci
     - run: npm run compile
     - run: npm run lint
+    - name: Run tests (headless)
+      shell: bash
+      run: |
+        if [ "$RUNNER_OS" = "Linux" ]; then
+          xvfb-run -a npm run test:ci
+        else
+          npm run test:ci
+        fi
+    - name: Verify VSIX file list
+      run: npx --yes @vscode/vsce ls
+    - name: Package extension (verification only)
+      run: npx --yes @vscode/vsce package --out write-good-linter.vsix

.gitignore

@@ -2,4 +2,5 @@ out
 node_modules
 write-good-linter-*.vsix
 .DS_Store
-test.md
+test.md
+.vscode-test

.vscodeignore

@@ -2,9 +2,14 @@
 typings/**
 out/test/**
 test/**
-src/**
-**/*.map
-.gitignore
-tsconfig.json
-vsc-extension-quickstart.md
-write-good-linter-*.vsix
+src/**
+**/*.map
+.gitignore
+tsconfig.json
+vsc-extension-quickstart.md
+write-good-linter-*.vsix
+.vscode-test/**
+node_modules/**/test/**
+node_modules/**/spec/**
+node_modules/**/.travis.yml
+node_modules/**/.github/**

AGENTS.md

@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/`: TypeScript sources. `extension.ts` wires activation, diagnostics, and settings; `linter.ts` wraps the `write-good` engine.
+- `out/`: Compiled JavaScript. Generated by `tsc`; do not edit.
+- Config: `package.json` (VS Code contributions, scripts), `tsconfig.json`, `eslint.config.mjs`.
+- CI: `.github/workflows/node.js.yml` runs install, compile, and lint on pushes/PRs.
+- Workspace: `.vscode/` contains local launch/debug config for Extension Development Host.
+
+## Build, Test, and Development Commands
+- `npm ci`: Clean install dependencies (used in CI).
+- `npm run compile`: Build TypeScript to `out/`.
+- `npm run watch`: Incremental rebuild during development.
+- `npm run lint`: Lint `src/**/*.ts` via ESLint.
+- Run locally: Open in VS Code and press F5 to launch the Extension Development Host; open a Markdown file to see diagnostics.
+- Publish (maintainers): `vsce publish` after `npm run compile` and `npm run lint`.
+
+## Coding Style & Naming Conventions
+- Language: TypeScript. Indent 4 spaces; end statements with semicolons.
+- Names: `camelCase` for variables/functions, `PascalCase` for types/interfaces, short lowercase filenames (e.g., `extension.ts`).
+- Linting: ESLint with `@typescript-eslint`. Enforced rules include `semi: always`; some strict TS rules are relaxed. Run `npm run lint` and fix warnings.
+
+## Testing Guidelines
+- End-to-end tests: `@vscode/test-electron` + Mocha/Chai.
+- Structure: `test/runTest.ts` (boot), `test/suite/*.test.ts` (specs), fixtures under `test/fixtures/ws/`.
+- Commands: `npm test` (headless by default), `npm run test:gui` (shows Dev Host), `npm run test:ci` (forces headless; used in CI).
+- Scenarios: diagnostics for Markdown, language filtering, "only lint on save", and debounce behavior.
+- Tips: set `write-good.debounce-time-in-ms` to `0` for deterministic checks unless testing debounce; create temp files in tests to avoid cross-test state.
+
+## Commit & Pull Request Guidelines
+- Commits: Imperative, concise subject (≤72 chars). Example: `lint: fix debounce handling in onDidChange`.
+- Reference issues/PRs when relevant (e.g., `Fixes #123`).
+- PRs must: describe intent and approach, list user-facing changes (settings/diagnostics), include before/after screenshots or GIFs when behavior changes, and pass CI (install, compile, lint).
+
+## Configuration Tips
+- Key settings forwarded to `write-good`:
+  - Example `settings.json` snippet:
+    ```json
+    {
+      "write-good.languages": ["markdown", "plaintext"],
+      "write-good.only-lint-on-save": false,
+      "write-good.debounce-time-in-ms": 200,
+      "write-good.write-good-config": { "eprime": true }
+    }
+    ```
+- Avoid editing `out/`; make changes in `src/` and rebuild.

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.7 — 2025-08-24
+- Added end-to-end behavioral tests using `@vscode/test-electron` + Mocha/Chai under `test/`.
+- New npm scripts: `test`, `test:gui`, and `test:ci`; CI runs headless tests.
+- CI now verifies VSIX contents (`vsce ls`) and builds the package (`vsce package`).
+- Documentation: added `AGENTS.md` and `CONTRIBUTING.md`; updated `README.md` with Testing section.
+- Packaging: updated `.vscodeignore` to exclude `test/**`, `out/test/**`, `.vscode-test/**`, and dependency `test/spec` files.
+- Repo hygiene: added `.vscode-test` to `.gitignore`; removed unused `value-check.js`.
+- Dependency updates: bumped ESLint/TypeScript toolchain, `@types/vscode`, Mocha/Chai, etc.
+

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thanks for helping improve Write Good Linter! This guide is a quick start. For full contributor guidelines, see Repository Guidelines.
+
+- Read: [Repository Guidelines](./AGENTS.md)
+- Publishing steps: [README – Publishing](./README.md#publishing)
+
+## Quick Setup
+1. Fork and clone your fork.
+2. Install Node.js (LTS or 22.x) and run:
+   ```bash
+   npm ci
+   npm run compile # or: npm run watch
+   ```
+3. Open the folder in VS Code and press F5 to launch the Extension Development Host. Open a Markdown file to see diagnostics.
+
+## Before You Open a PR
+- Ensure code is in `src/` only; do not edit `out/`.
+- Run formatting/linting and build:
+  ```bash
+  npm run lint
+  npm run compile
+  ```
+- Run tests and ensure all specs pass:
+  ```bash
+  npm test        # headless
+  # or for visual debugging
+  npm run test:gui
+  ```
+- Manually verify behavior in the Dev Host (F5), including settings like `write-good.only-lint-on-save` and `write-good.debounce-time-in-ms`.
+
+## Pull Requests
+- Use concise, imperative commit messages (e.g., "fix: debounce scheduling").
+- PR description should include: purpose, approach, user-facing changes (settings/diagnostics), and screenshots/GIFs if behavior changes.
+- Link related issues (e.g., "Fixes #123").
+- CI must pass (install, compile, lint).
+
+## Issues
+- When filing a bug, include VS Code version, OS, sample text that reproduces the warning, relevant settings, and logs from the Extension Host if applicable.

README.md

@@ -30,6 +30,16 @@ Open up the project in Visual Studio Code and hit F5 to open up a *developement
 
 Check out the [Extending Visual Studio Code](https://code.visualstudio.com/Docs/extensions/overview) documentation for more information.
 
+## Testing
+
+- Install and run: `npm ci` then `npm test`. The first run downloads a VS Code build for testing.
+- GUI vs headless:
+  - Local GUI: `npm run test:gui` opens an Extension Development Host for visual debugging.
+  - Headless CI: `npm run test:ci` forces headless mode (used in GitHub Actions).
+- Layout: tests live in `test/suite/*.test.ts`; fixtures in `test/fixtures/ws`. The runner is `test/runTest.ts` (uses `@vscode/test-electron`).
+- Covered scenarios: diagnostics on bad Markdown, language filtering, only‑lint‑on‑save, and debounce behavior.
+- Tips: if timing is flaky locally, re‑run `npm test` or use GUI mode to observe behavior. Tests should not modify `out/`.
+
 ## Publishing
 
 1. `npm install -g vsce`