feat: clickable diagnostic codes, .explcheckrc awareness, remote support (v0.2.1)

- Diagnostic codes link to the explcheck rule docs (phase-specific markdown,
  chosen by the rule's leading digit — explcheck has no per-rule anchors)
- Run explcheck from the workspace root so project-level .explcheckrc applies
  to files in subdirectories (explcheck searches cwd only, no upward walk)
- extensionKind: [workspace] — diagnostics need the local explcheck binary,
  so the extension must run workspace-side under Remote-SSH / Dev Containers
- Settings use markdownDescription; README gains a diagnostics screenshot
  (rendered from real explcheck output) and an as-you-type / .explcheckrc note

Author: Liam0205

.vscodeignore

@@ -6,6 +6,7 @@ node_modules/**
 src/**
 tests/**
 images/before-after.*
+images/diagnostics.*
 tsconfig.json
 package-lock.json
 **/*.ts

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.2.1] - 2026-07-06
+
+### Added
+
+- Diagnostic codes are now clickable and link to the relevant `explcheck`
+  documentation (the phase-specific rule reference).
+- `.explcheckrc` project config is respected: checks run from the workspace
+  root, so a root-level config applies to files in subdirectories.
+
+### Changed
+
+- Declared `extensionKind: ["workspace"]` so diagnostics work correctly in
+  Remote-SSH / Dev Containers (explcheck runs on the workspace side).
+- Settings use `markdownDescription` for richer links and formatting.
+- README gains a diagnostics screenshot and an as-you-type / `.explcheckrc` note.
+
 ## [0.2.0] - 2026-07-06
 
 ### Added

README.md

@@ -29,6 +29,8 @@ looks native in Dark+, Light+, Solarized, and everything else.
 If [`explcheck`](https://ctan.org/pkg/expltools) is available, the extension runs it
 on your expl3 files and shows the results as squiggles, mapped by severity:
 
+![explcheck diagnostics](https://raw.githubusercontent.com/CTeX-org/expl3-vscode/main/images/diagnostics.png)
+
 | explcheck prefix | meaning | VS Code severity |
 |------------------|---------|------------------|
 | `e`, `t` | errors / type errors | Error |
@@ -58,6 +60,10 @@ keeps working regardless.
 
 Command **expl3: Run explcheck on the active file** triggers a check on demand.
 
+Project-level [`.explcheckrc`](https://ctan.org/pkg/expltools) config is respected:
+checks run from the workspace root, so a `.explcheckrc` at the project root applies
+even to files in subdirectories.
+
 #### Live (as-you-type) checking
 
 By default checks run on save (`onSave`). To lint **as you type**, set:

images/diagnostics.png

@@ -2,7 +2,7 @@
   "name": "expl3-vscode",
   "displayName": "expl3 (LaTeX3) Language Support",
   "description": "Syntax highlighting and explcheck diagnostics for expl3 (LaTeX3) code.",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publisher": "CTeX-org",
   "license": "MIT",
   "icon": "images/icon.png",
@@ -36,6 +36,9 @@
   },
   "homepage": "https://github.com/CTeX-org/expl3-vscode#readme",
   "main": "./dist/extension.js",
+  "extensionKind": [
+    "workspace"
+  ],
   "activationEvents": [
     "onLanguage:latex",
     "onLanguage:latex-expl3",
@@ -78,12 +81,12 @@
         "expl3.check.enable": {
           "type": "boolean",
           "default": true,
-          "description": "Enable explcheck static analysis diagnostics."
+          "markdownDescription": "Enable [`explcheck`](https://ctan.org/pkg/expltools) static-analysis diagnostics."
         },
         "expl3.check.path": {
           "type": "string",
           "default": "explcheck",
-          "description": "Path to the explcheck executable. Defaults to `explcheck` on PATH (provided by the TeX Live `expltools` package)."
+          "markdownDescription": "Path to the `explcheck` executable. Defaults to `explcheck` on `PATH` (provided by the TeX Live [`expltools`](https://ctan.org/pkg/expltools) package)."
         },
         "expl3.check.run": {
           "type": "string",
@@ -98,31 +101,31 @@
             "Only run explcheck via the 'expl3: Run explcheck' command."
           ],
           "default": "onSave",
-          "description": "When to run explcheck diagnostics. Use 'onType' for live as-you-type checking."
+          "markdownDescription": "When to run explcheck diagnostics. Use `onType` for live as-you-type checking."
         },
         "expl3.check.debounce": {
           "type": "number",
           "default": 400,
           "minimum": 100,
-          "description": "Debounce delay in milliseconds for `onType` checking."
+          "markdownDescription": "Debounce delay in milliseconds for `onType` checking."
         },
         "expl3.check.maxLineLength": {
           "type": "number",
           "default": 0,
-          "description": "Max line length before the S103 (line too long) warning. 0 uses explcheck's default (80)."
+          "markdownDescription": "Max line length before the `s103` (line too long) warning. `0` uses explcheck's default (80)."
         },
         "expl3.check.ignoredIssues": {
           "type": "array",
           "items": {
             "type": "string"
           },
           "default": [],
-          "description": "Issue identifiers or prefixes to suppress (passed to explcheck --ignored-issues), e.g. [\"s103\", \"w2\"]."
+          "markdownDescription": "Issue identifiers or prefixes to suppress (passed to `explcheck --ignored-issues`), e.g. `[\"s103\", \"w2\"]`."
         },
         "expl3.check.makeAtLetter": {
           "type": "boolean",
           "default": false,
-          "description": "Tokenize @ as a letter (catcode 11), like in LaTeX .sty files (explcheck --make-at-letter)."
+          "markdownDescription": "Tokenize `@` as a letter (catcode 11), like in LaTeX `.sty` files (`explcheck --make-at-letter`)."
         }
       }
     }

images/diagnostics.svg

@@ -35,6 +35,27 @@ function severityOf(t: string): vscode.DiagnosticSeverity {
   }
 }
 
+// explcheck has no per-rule HTML page (docs are PDF + pandoc markdown, and
+// GitHub does not honour the pandoc {label=...} anchors). The best stable link
+// is the phase-specific markdown source, chosen by the rule's leading digit.
+// Users land on the right document and can search for the code. Falls back to
+// the intro for anything unrecognised.
+const DOC_BASE =
+  "https://github.com/witiko/expltools/blob/main/explcheck/doc/";
+const PHASE_DOC: Record<string, string> = {
+  "1": "warnings-and-errors-01-preprocessing.md",
+  "2": "warnings-and-errors-02-lexical-analysis.md",
+  "3": "warnings-and-errors-03-syntactic-analysis.md",
+  "4": "warnings-and-errors-04-semantic-analysis.md",
+  "5": "warnings-and-errors-05-flow-analysis.md",
+};
+function ruleDocUri(code: string): vscode.Uri {
+  const digit = code.replace(/^[a-z]/i, "").charAt(0);
+  const file = PHASE_DOC[digit] ?? "warnings-and-errors-00-introduction.md";
+  return vscode.Uri.parse(DOC_BASE + file);
+}
+
+
 function config() {
   return vscode.workspace.getConfiguration("expl3");
 }
@@ -47,6 +68,15 @@ function explcheckPath(): string {
   return config().get<string>("check.path", "explcheck") || "explcheck";
 }
 
+// explcheck looks for `.explcheckrc` in its cwd only (no upward search).
+// Run it from the workspace root so a project-level config is picked up
+// regardless of where the checked file sits. Falls back to the file's dir.
+function execCwd(docUri: vscode.Uri): string {
+  const folder = vscode.workspace.getWorkspaceFolder(docUri);
+  if (folder) return folder.uri.fsPath;
+  return path.dirname(docUri.fsPath);
+}
+
 // Should we lint this document? Skip .dtx by extension even if the language id
 // happens to resolve to latex, since explcheck rejects .dtx outright.
 function isLintable(doc: vscode.TextDocument): boolean {
@@ -83,7 +113,7 @@ function runExplcheck(
   cp.execFile(
     exe,
     buildArgs(target),
-    { maxBuffer: 8 * 1024 * 1024 },
+    { maxBuffer: 8 * 1024 * 1024, cwd: execCwd(docUri) },
     (err, stdout, stderr) => {
       // ENOENT => explcheck not installed / not on PATH.
       if (err && (err as NodeJS.ErrnoException).code === "ENOENT") {
@@ -120,7 +150,8 @@ function parseOutput(stdout: string, target: string): vscode.Diagnostic[] {
       severityOf(m.groups.t),
     );
     diag.source = "explcheck";
-    diag.code = code;
+    // Clickable code that links to the rule's documentation.
+    diag.code = { value: code, target: ruleDocUri(code) };
     diags.push(diag);
   }
   return diags;
@@ -161,7 +192,7 @@ function runExplcheckTemp(
   cp.execFile(
     exe,
     buildArgs(tmp),
-    { maxBuffer: 8 * 1024 * 1024 },
+    { maxBuffer: 8 * 1024 * 1024, cwd: execCwd(docUri) },
     (err, stdout) => {
       fs.unlink(tmp, () => {});
       if (err && (err as NodeJS.ErrnoException).code === "ENOENT") {