add docs and AI skills

2026-08-17 18:23:10 +02:00
parent c3d5d3541b
commit 09dcfede46
13 changed files with 506 additions and 0 deletions
@@ -0,0 +1,56 @@
+---
+name: verify-eftl-linter
+description: Verify the EFTL linter and VS Code language support with repository checks, tokenizer/parser cases, diagnostic range review, TextMate grammar checks, snippets, examples, and LSP behavior. Use after EFTL implementation changes, while diagnosing regressions, when adding tests, or before declaring a linter feature complete.
+---
+
+# Verify EFTL Linter
+
+Validate the core language implementation first, then the LSP and editor surfaces affected by the change. Read [references/verification-matrix.md](references/verification-matrix.md) when selecting cases.
+
+## Run the baseline check
+
+From the repository root, run:
+
+```powershell
+node .agents/skills/verify-eftl-linter/scripts/check-repository.mjs
+```
+
+The script parses contributed JSON, checks referenced files, compiles TypeScript, runs an existing test script when present, and smoke-tests the compiled tokenizer/parser. Pass `--lint` only when the repository has a working ESLint configuration.
+
+Treat this script as a floor, not as feature proof.
+
+## Build a focused test set
+
+For each changed rule, include:
+
+- the smallest valid form;
+- every optional form or bodyless/block alternative;
+- a representative nested form;
+- missing, duplicated, invalid, and out-of-order attributes or children;
+- mismatched, missing, and unexpected closing delimiters;
+- incomplete input at end of file for live-edit recovery;
+- lowercase and mixed-case spellings when the runtime is case-insensitive;
+- LF, CRLF, multiline, and non-ASCII range cases;
+- a regression case from `examples/` or the reported bug.
+
+Assert token types and spans separately from parser errors. Assert diagnostic code, severity, message, and exact LSP range; do not rely only on snapshot text.
+
+## Verify by layer
+
+1. Run tokenizer/parser tests without VS Code.
+2. Run server-level tests for config, diagnostic caps, declaration/reference scope, and range conversion.
+3. Parse all JSON contribution files and inspect TextMate captures for the changed construct.
+4. Open a representative `.eftl` file in an Extension Development Host when highlighting, folding, snippets, activation, or navigation changed.
+5. Confirm valid examples produce no diagnostics and each invalid example produces the intended minimal set.
+
+When no automated harness exists for a required layer, add one if it is stable and proportionate; otherwise document the exact manual check and result.
+
+## Interpret failures
+
+- A compilation failure blocks all further verification.
+- A failure caused by a known baseline issue must be reproduced on the pre-change baseline before being labeled unrelated.
+- Diagnostic cascades usually indicate parser recovery problems; fix recovery instead of weakening assertions.
+- TextMate highlighting success does not prove tokenizer/parser support, and parser success does not prove editor integration.
+- Never declare `npm run lint` successful in the current baseline: ESLint 9 has no flat configuration until the repository adds one.
+
+Report commands, pass/fail counts, skipped layers, and residual risks.