build: adopt Oxfmt and enforce TypeScript formatting in CI (#1825)

## Summary

Follow up on #1818 and the toolchain review in #1732 by introducing a shared formatter and checking formatting in CI. After the ESLint migration, contributors had no formatting command or CI check; this PR provides both and formats the existing TypeScript sources consistently.

To keep the diff reviewable, formatting is limited to TypeScript files (`.ts`, `.tsx`, `.mts`, `.cts`) for now. Other file types can be enabled in follow-up PRs.

- Pin Oxfmt to 0.73.0 and add `pnpm run format` / `pnpm run format:check`.
- Share `.oxfmtrc.jsonc` between the CLI and the already recommended Oxc editor extension. Restrict the scope to TypeScript via `ignorePatterns`, use four-space indentation and single quotes, and disable import and package metadata sorting. Generated output (`out/`, `dist/`) is skipped through the existing Git ignore rules.
- Format 173 TypeScript files (169 under `src/`, 4 under `html/`) in a dedicated mechanical commit. Move one `no-control-regex` suppression comment next to the regular expression after line wrapping moved it to another line.
- Add an independent `format` CI job with Node.js 24, frozen-lockfile installation, and `pnpm run format:check`. Enable format on save for TypeScript and document the contributor commands.

Author: eitsupi

.github/workflows/main.yml

@@ -128,6 +128,18 @@ jobs:
         with:
           name: ${{ env.VSIX_FILE }}
           path: ${{ env.VSIX_FILE }}
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - name: Check TypeScript formatting
+        run: pnpm run format:check
   lint:
     runs-on: ubuntu-latest
     env:

.oxfmtrc.jsonc

@@ -0,0 +1,14 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 100,
+  "tabWidth": 4,
+  "singleQuote": true,
+  "endOfLine": "lf",
+  // Keep imports and package metadata in their existing order.
+  "sortImports": false,
+  "sortPackageJson": false,
+  // Format TypeScript files only for now: ignore everything, then re-include
+  // directories and TypeScript sources. The CLI and the Oxc VS Code extension
+  // both read this file.
+  "ignorePatterns": ["*", "!*/", "!*.ts", "!*.tsx", "!*.mts", "!*.cts"],
+}

.vscode/settings.json

@@ -7,6 +7,10 @@
         "out": true // set this to false to include "out" folder in search results
     },
     "r.lsp.diagnostics": true,
+    "[typescript][typescriptreact]": {
+        "editor.defaultFormatter": "oxc.oxc-vscode",
+        "editor.formatOnSave": true
+    },
     "editor.codeActionsOnSave": {
         "source.fixAll.markdownlint": "explicit"
     }

CONTRIBUTING.md

@@ -25,6 +25,27 @@ If launching reports `Configured debug type 'extensionHost' is not supported`, e
 
 On VS Code 1.139, the regression can leave the development host paused before any extension activates; the launching window's extension host log shows `ECONNREFUSED ::1` and `Could not find any debuggable target`. Upgrade to VS Code 1.140.0 or newer, or use Microsoft's [JavaScript Debugger Nightly](https://marketplace.visualstudio.com/items?itemName=ms-vscode.js-debug-nightly) as a temporary workaround: disable the built-in **JavaScript Debugger**, enable Nightly, and reload VS Code.
 
+## Formatting and linting
+
+Run `pnpm run format` to format TypeScript files with Oxfmt, and
+`pnpm run format:check` to check formatting without changing files. CI runs the
+same check for pull requests and pushes to `main`. Formatting currently applies
+to TypeScript files only (`.ts`, `.tsx`, `.mts`, and `.cts`); other file types,
+including JavaScript, JSON, Markdown, YAML, R, C, and EJS files, are not formatted.
+
+The checked-in `.oxfmtrc.jsonc` is shared by the CLI and the recommended Oxc
+VS Code extension, and its `ignorePatterns` restrict both to TypeScript files.
+TypeScript files use four-space indentation and single quotes. Import and
+`package.json` sorting are disabled. The CLI also respects the repository's
+`.gitignore` files, so generated bundles, compiled tests, and dependencies are
+excluded from `pnpm run format` and `pnpm run format:check`. The editor
+integration does not apply `.gitignore`, so it can still format generated files
+under `out/` or `dist/` if you open and save them.
+
+Workspace settings select Oxc as the formatter and enable format on save for
+TypeScript. Run `pnpm run lint` and `pnpm run typecheck` separately to check
+TypeScript code.
+
 ## Building bundled sess
 
 Builds require Git and a checkout with HEAD. `scripts/prepare-sess.js` fingerprints

html/help/script.ts

@@ -8,30 +8,27 @@ window.onmousedown = (ev) => {
     vscode.postMessage({
         message: 'mouseClick',
         button: Number(ev.button),
-        scrollY: window.scrollY
+        scrollY: window.scrollY,
     });
 };
 
-
 // handle requests from vscode ui
 window.addEventListener('message', (ev: MessageEvent) => {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const message = ev.data;
     // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    if(message.command === 'getScrollY'){
+    if (message.command === 'getScrollY') {
         vscode.postMessage({
             message: 'getScrollY',
-            scrollY: window.scrollY
+            scrollY: window.scrollY,
         });
     }
 });
 
-
 // do everything after loading the body
 window.document.body.onload = () => {
-
     // make relative path for hyperlinks
-    const relPath = (document.body.getAttribute('relPath') || '');
+    const relPath = document.body.getAttribute('relPath') || '';
 
     // notify vscode, used to restore help panels between sessions
     vscode.setState(relPath);
@@ -42,42 +39,41 @@ window.document.body.onload = () => {
 
     // scroll to desired position:
     const scrollYTo = Number(document.body.getAttribute('scrollYTo') ?? -1);
-    if(scrollYTo >= 0){
-        window.scrollTo(0,scrollYTo);
-    } else if(url1.hash){
+    if (scrollYTo >= 0) {
+        window.scrollTo(0, scrollYTo);
+    } else if (url1.hash) {
         document.location.hash = url1.hash;
     }
 
     // notify vscode when links are clicked:
     const hyperLinks = document.getElementsByTagName('a');
 
-    for(let i=0; i<hyperLinks.length; i++){
+    for (let i = 0; i < hyperLinks.length; i++) {
         const hrefAbs = hyperLinks[i].href;
         const hrefRel = hyperLinks[i].getAttribute('href') || '';
 
-        if(hrefRel.startsWith('#')){
+        if (hrefRel.startsWith('#')) {
             hyperLinks[i].onclick = () => {
                 document.location.hash = hrefRel;
             };
-        } else if(hrefAbs && hrefAbs.startsWith('vscode-webview://')){
+        } else if (hrefAbs && hrefAbs.startsWith('vscode-webview://')) {
             hyperLinks[i].onclick = () => {
-
                 const url2 = new URL(hrefRel, url1);
                 const finalHref = url2.toString();
 
                 vscode.postMessage({
                     message: 'linkClicked',
                     href: finalHref,
-                    scrollY: window.scrollY
+                    scrollY: window.scrollY,
                 });
             };
         }
     }
 
     // notify vscode when code is clicked:
-    if(document.body.classList.contains('preClickable')){
+    if (document.body.classList.contains('preClickable')) {
         const codeElements = document.getElementsByTagName('pre');
-        for(let i=0; i<codeElements.length; i++){
+        for (let i = 0; i < codeElements.length; i++) {
             const el = codeElements[i];
             el.onclick = (me: MouseEvent) => {
                 vscode.postMessage({
@@ -88,10 +84,9 @@ window.document.body.onload = () => {
                         ctrlKey: me.ctrlKey,
                         shiftKey: me.shiftKey,
                         metaKey: me.metaKey,
-                    }
+                    },
                 });
             };
         }
     }
 };
-

html/help/webviewMessages.d.ts

@@ -5,38 +5,41 @@ interface VsCode {
     setState: (state: string) => void;
 }
 
-
 interface IOutMessage {
     message: string;
 }
 interface LogMessage extends IOutMessage {
-    message: 'log',
-    body: any
+    message: 'log';
+    body: any;
 }
 interface MouseClickMessage extends IOutMessage {
-    message: 'mouseClick',
-    button: number,
-    scrollY: number
+    message: 'mouseClick';
+    button: number;
+    scrollY: number;
 }
 interface LinkClickedMessage extends IOutMessage {
-    message: 'linkClicked',
-    href: string,
-    scrollY: number
+    message: 'linkClicked';
+    href: string;
+    scrollY: number;
 }
 interface CodeClickedMessage extends IOutMessage {
-    message: 'codeClicked',
-    code: string,
+    message: 'codeClicked';
+    code: string;
     modifiers: {
-        altKey: boolean,
-        ctrlKey: boolean,
-        shiftKey: boolean,
-        metaKey: boolean,
-    }
+        altKey: boolean;
+        ctrlKey: boolean;
+        shiftKey: boolean;
+        metaKey: boolean;
+    };
 }
 interface GetScrollYMessage extends IOutMessage {
-    message: 'getScrollY',
-    scrollY: number
+    message: 'getScrollY';
+    scrollY: number;
 }
 
-type OutMessage = LogMessage | MouseClickMessage | LinkClickedMessage | CodeClickedMessage | GetScrollYMessage;
-
+type OutMessage =
+    | LogMessage
+    | MouseClickMessage
+    | LinkClickedMessage
+    | CodeClickedMessage
+    | GetScrollYMessage;