chore: start lint with workers.

Author: knightedcodemonkey

docs/lint-workers.md

@@ -0,0 +1,72 @@
+# Lint Workers Plan
+
+This document defines the worker-based lint architecture for component and styles
+panels in `@knighted/develop`.
+
+## Goals
+
+- Use `eslint@10` for component linting.
+- Use `stylelint` for style linting.
+- Run both in Web Workers so preview/typecheck remain responsive.
+- Reuse shared request/response and diagnostics formatting logic.
+- Keep ESLint and Stylelint implementations in separate modules.
+
+## Module Layout
+
+Main thread:
+
+- `src/modules/lint/lint-controller.js`: orchestrates component/style lint flows.
+- `src/modules/lint/eslint/worker-adapter.js`: ESLint request adapter.
+- `src/modules/lint/stylelint/worker-adapter.js`: Stylelint request adapter.
+- `src/modules/lint/shared/worker-client.js`: worker RPC, timeout, cancellation.
+- `src/modules/lint/shared/protocol.js`: shared message contract.
+- `src/modules/lint/shared/format.js`: shared diagnostics normalization/formatting.
+
+Worker thread:
+
+- `src/modules/lint-worker.js`: worker entrypoint and engine dispatch.
+- `src/modules/lint/worker/runtime-loader.js`: runtime loading with CDN candidates.
+- `src/modules/lint/worker/eslint-runtime.js`: ESLint execution path.
+- `src/modules/lint/worker/stylelint-runtime.js`: Stylelint execution path.
+
+Engine-specific config:
+
+- `src/modules/lint/eslint/config.js`: ESLint lint options.
+- `src/modules/lint/stylelint/config.js`: Stylelint lint options and syntax map.
+
+## Rollout Phases
+
+1. Scaffold worker runtime plumbing.
+2. Wire panel actions in `src/index.html` and `src/app.js` for:
+   - Component Lint
+   - Styles Lint
+3. Keep lint on-demand first; avoid auto-lint until runtime stability is proven.
+4. Add line/column click navigation to editors once diagnostics UI supports
+   structured entries.
+5. Add Playwright coverage for:
+   - Component lint success and error scenarios.
+   - Style lint success for `css`, `module`, `less`, and `sass` modes.
+   - Timeout/unavailable runtime fallback states.
+
+## Runtime Notes
+
+- `eslint@10` is the target runtime.
+- Stylelint syntax handling is dialect-aware:
+  - `css`, `module` -> default CSS syntax.
+  - `less` -> `postcss-less` custom syntax.
+  - `sass` -> `postcss-scss` custom syntax.
+- Runtime loading currently uses CDN candidate fallback and should stay lazy.
+
+## Virtual Filesystem Policy
+
+- Baseline linting is single-file and does not require a virtual filesystem.
+- If cross-file linting becomes required, do not roll a custom virtual
+  filesystem implementation first.
+- Prefer a maintained virtual filesystem library with browser-worker support and
+  predictable path normalization semantics.
+
+## Follow-up Tasks
+
+- Confirm browser-compatible runtime bundles for ESLint 10 + required plugins.
+- Confirm browser-compatible stylelint bundle path and syntax plugin availability.
+- Move diagnostics scope rendering from string-only lines to structured entries.

src/app.js

@@ -8,6 +8,7 @@ import { createCodeMirrorEditor } from './modules/editor-codemirror.js'
 import { defaultCss, defaultJsx, defaultReactJsx } from './modules/defaults.js'
 import { createDiagnosticsUiController } from './modules/diagnostics-ui.js'
 import { createLayoutThemeController } from './modules/layout-theme.js'
+import { createLintController } from './modules/lint/lint-controller.js'
 import { createPreviewBackgroundController } from './modules/preview-background.js'
 import { createRenderRuntimeController } from './modules/render-runtime.js'
 import { createTypeDiagnosticsController } from './modules/type-diagnostics.js'
@@ -24,6 +25,8 @@ const previewPanel = document.getElementById('preview-panel')
 const renderMode = document.getElementById('render-mode')
 const autoRenderToggle = document.getElementById('auto-render')
 const typecheckButton = document.getElementById('typecheck-button')
+const lintComponentButton = document.getElementById('lint-component-button')
+const lintStylesButton = document.getElementById('lint-styles-button')
 const renderButton = document.getElementById('render-button')
 const copyComponentButton = document.getElementById('copy-component')
 const clearComponentButton = document.getElementById('clear-component')
@@ -369,6 +372,16 @@ const setTypecheckButtonLoading = isLoading => {
   typecheckButton.disabled = isLoading
 }
 
+const setLintButtonLoading = ({ button, isLoading }) => {
+  if (!(button instanceof HTMLButtonElement)) {
+    return
+  }
+
+  button.classList.toggle('render-button--loading', isLoading)
+  button.setAttribute('aria-busy', isLoading ? 'true' : 'false')
+  button.disabled = isLoading
+}
+
 const setCdnLoading = isLoading => {
   if (!cdnLoading) return
   cdnLoading.hidden = !isLoading
@@ -409,6 +422,49 @@ const typeDiagnostics = createTypeDiagnosticsController({
   getActiveTypeDiagnosticsRuns,
 })
 
+const lintController = createLintController({
+  getComponentSource: () => getJsxSource(),
+  getStylesSource: () => getCssSource(),
+  getRenderMode: () => renderMode.value,
+  getStyleMode: () => styleMode.value,
+  setComponentDiagnostics: setTypeDiagnosticsDetails,
+  setStyleDiagnostics: setStyleDiagnosticsDetails,
+  setStatus,
+})
+
+let activeComponentLintAbortController = null
+let activeStylesLintAbortController = null
+
+const runComponentLint = async () => {
+  activeComponentLintAbortController?.abort()
+  activeComponentLintAbortController = new AbortController()
+
+  setLintButtonLoading({ button: lintComponentButton, isLoading: true })
+
+  try {
+    await lintController.lintComponent({
+      signal: activeComponentLintAbortController.signal,
+    })
+  } finally {
+    setLintButtonLoading({ button: lintComponentButton, isLoading: false })
+  }
+}
+
+const runStylesLint = async () => {
+  activeStylesLintAbortController?.abort()
+  activeStylesLintAbortController = new AbortController()
+
+  setLintButtonLoading({ button: lintStylesButton, isLoading: true })
+
+  try {
+    await lintController.lintStyles({
+      signal: activeStylesLintAbortController.signal,
+    })
+  } finally {
+    setLintButtonLoading({ button: lintStylesButton, isLoading: false })
+  }
+}
+
 const markTypeDiagnosticsStale = () => {
   typeDiagnostics.markTypeDiagnosticsStale()
 }
@@ -607,6 +663,16 @@ if (typecheckButton) {
     typeDiagnostics.triggerTypeDiagnostics()
   })
 }
+if (lintComponentButton) {
+  lintComponentButton.addEventListener('click', () => {
+    void runComponentLint()
+  })
+}
+if (lintStylesButton) {
+  lintStylesButton.addEventListener('click', () => {
+    void runStylesLint()
+  })
+}
 renderButton.addEventListener('click', renderPreview)
 if (clipboardSupported) {
   copyComponentButton.addEventListener('click', () => {
@@ -699,6 +765,10 @@ if (typeof compactViewportMediaQuery.addEventListener === 'function') {
   compactViewportMediaQuery.onchange = handleCompactViewportChange
 }
 
+window.addEventListener('beforeunload', () => {
+  lintController.dispose()
+})
+
 applyAppGridLayout(getInitialAppGridLayout(), { persist: false })
 applyTheme(getInitialTheme(), { persist: false })
 applyEditorToolsVisibility()

src/index.html

@@ -208,6 +208,9 @@ <h2>Component</h2>
                 <button class="render-button" id="typecheck-button" type="button">
                   Typecheck
                 </button>
+                <button class="render-button" id="lint-component-button" type="button">
+                  Lint
+                </button>
                 <label>
                   <span class="sr-only">Render mode</span>
                   <select id="render-mode">
@@ -291,6 +294,9 @@ <h2>Styles</h2>
             </div>
             <div class="panel-header-main-actions">
               <div class="controls controls--actions">
+                <button class="render-button" id="lint-styles-button" type="button">
+                  Lint
+                </button>
                 <label>
                   <span class="sr-only">Style mode</span>
                   <select id="style-mode">

src/modules/cdn.js

@@ -138,6 +138,13 @@ export const cdnImportSpecs = {
     esm: '@codemirror/lang-css',
     jspmGa: 'npm:@codemirror/lang-css@6.3.1',
   },
+  eslintRuntime: {
+    esm: ['eslint@10?bundle', 'eslint@10/use-at-your-own-risk?bundle'],
+  },
+  stylelintRuntime: {
+    esm: 'stylelint@17.4.0?bundle',
+    jspmGa: 'npm:stylelint@17.4.0/lib/index.mjs',
+  },
 }
 
 const getProviderPriority = () => {

src/modules/lint-worker.js

@@ -0,0 +1,84 @@
+import {
+  isLintCancelMessage,
+  isLintRequestMessage,
+  lintEngines,
+  lintWorkerMessageTypes,
+} from './lint/shared/protocol.js'
+import { runEslintLint } from './lint/worker/eslint-runtime.js'
+import { runStylelintLint } from './lint/worker/stylelint-runtime.js'
+
+const canceledIds = new Set()
+
+const toErrorMessage = error => {
+  if (error instanceof Error && error.message) {
+    return error.message
+  }
+
+  return String(error)
+}
+
+const runEngineLint = async payload => {
+  if (payload.engine === lintEngines.eslint) {
+    return runEslintLint({
+      source: payload.source,
+      filename: payload.filename,
+      renderMode: payload.mode ?? 'dom',
+    })
+  }
+
+  if (payload.engine === lintEngines.stylelint) {
+    return runStylelintLint({
+      source: payload.source,
+      filename: payload.filename,
+      styleMode: payload.mode ?? 'css',
+    })
+  }
+
+  throw new Error(`Unknown lint engine: ${payload.engine}`)
+}
+
+self.addEventListener('message', async event => {
+  const message = event.data
+
+  if (isLintCancelMessage(message)) {
+    canceledIds.add(message.id)
+    return
+  }
+
+  if (!isLintRequestMessage(message)) {
+    return
+  }
+
+  const { id, payload } = message
+
+  if (canceledIds.has(id)) {
+    canceledIds.delete(id)
+    return
+  }
+
+  try {
+    const diagnostics = await runEngineLint(payload)
+
+    if (canceledIds.has(id)) {
+      canceledIds.delete(id)
+      return
+    }
+
+    self.postMessage({
+      type: lintWorkerMessageTypes.result,
+      id,
+      diagnostics,
+    })
+  } catch (error) {
+    if (canceledIds.has(id)) {
+      canceledIds.delete(id)
+      return
+    }
+
+    self.postMessage({
+      type: lintWorkerMessageTypes.error,
+      id,
+      message: toErrorMessage(error),
+    })
+  }
+})

src/modules/lint/eslint/config.js

@@ -0,0 +1,33 @@
+export const getEslintLintOptions = ({ renderMode }) => {
+  const reactRules =
+    renderMode === 'react'
+      ? {
+          'no-unused-vars': 'warn',
+        }
+      : {}
+
+  return {
+    ignore: false,
+    overrideConfigFile: true,
+    overrideConfig: [
+      {
+        files: ['**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'],
+        languageOptions: {
+          ecmaVersion: 'latest',
+          sourceType: 'module',
+          parserOptions: {
+            ecmaFeatures: {
+              jsx: true,
+            },
+          },
+        },
+        rules: {
+          'no-undef': 'error',
+          'no-unreachable': 'error',
+          'no-unused-vars': 'warn',
+          ...reactRules,
+        },
+      },
+    ],
+  }
+}

src/modules/lint/eslint/worker-adapter.js

@@ -0,0 +1,19 @@
+import { createLintRequest, lintEngines, lintScopes } from '../shared/protocol.js'
+
+export const createEslintWorkerAdapter = ({ client }) => {
+  const lintComponent = async ({ source, renderMode, signal }) => {
+    const request = createLintRequest({
+      engine: lintEngines.eslint,
+      scope: lintScopes.component,
+      source,
+      filename: 'component.tsx',
+      mode: renderMode,
+    })
+
+    return client.run(request, { signal })
+  }
+
+  return {
+    lintComponent,
+  }
+}