π OpenHands: AI-Driven Development
chore(lint): reject unknown Tailwind classes with verified theme loading (#17644)
πΎ smolpaws8bb2293410c3
diff --git a/.pr/lint-verification.md b/.pr/lint-verification.mdnew file mode 100644index 0000000000..3689ea5d3a--- /dev/null+++ b/.pr/lint-verification.md@@ -0,0 +1,87 @@+# Unknown-class lint adoption++Base: `a3cfe98267c52937dc4e91a55644a6131c6c01bc`. Pinned linter: `@shadcn/[email protected]`.++The rule is enabled at error level now that its initial findings are resolved. Four inert class usages are also removed; generated styling and the DOM structure are preserved.++## Inventory++`npx eslint src --rule 'shadcn/no-unknown-classes:warn' --format json` initially reported **6** unknown-class warnings, alongside **347** existing arbitrary-value warnings. No theme-loading or worker-fallback warnings were emitted.++Two exact exceptions are supported by code:++- `environment-switch-overlay`: `src/index.css:134` uses it to animate child elements; that stylesheet is outside the Tailwind theme import graph.+- `conversation-overview-diffs-git-action`: a selector target in `src/components/features/conversation/conversation-overview-diffs-row.tsx:40` for clearing row hover while the action is hovered.++All **4 genuine findings are fixed** by removing inert classes:++| File | Finding and correction |+| --- | --- |+| `src/components/features/chat/drag-over.tsx` | Remove `drag-over-content`, which has no stylesheet or selector consumer; retain the wrapper element. |+| `src/components/features/home/repo-selection-form.tsx` | Remove `max-w-auto`, which emits no CSS. |+| `src/components/features/home/workspace-selection-form.tsx` | Remove the same unsupported width class. |+| `src/utils/form-control-classes.ts` | Remove unsupported `ease`; retain the existing transform transition, duration, reduced-motion handling, and default timing. |++The dropdowns pass the optional class to `cn("relative", className)`; removing it does not reveal a previously overridden maximum width. Do not substitute `min-w-auto`: minimum width is a different property. Likewise, connecting the drag overlay to the similarly named `.drag-over-ui-content` rule would newly force white text and fixed typography. That is a separate visual decision, not necessary to remove an unused marker.++`node .pr/verify-inert-classes.mjs` verifies identical compiled CSS before/after removal with the actual Tailwind theme/plugins and checks that class merging preserves all valid utilities. A repository search found no CSS/JS/test consumers of the removed marker or utilities. The transition helper is shared by caret controls in both standalone and embedded Canvas, independent of backend/agent type; it retains its existing behavior in all consumers.++## Reproduction++Run `node .pr/verify-unknown-classes.mjs` from the repository root. It uses the actual ESLint config and virtual TSX under `src/ui`, verifying that the rule remains active inside component implementations.++Observed output:++```text+"hovr:flex" ... Did you mean "hover:flex"?+"flex-cols" ... Did you mean "flex-col"?+"environment-switch-overla" ... no CSS is generated for it.+PASS: real theme/plugins accepted; typos are errors; exceptions stay exact.+```++Accepted: Canvas surface/border/focus tokens, `prose`, `scrollbar-hide`, a HeroUI color with a data variant, and the two documented markers. This also detects the documented fallback mode that incorrectly accepts `hovr:flex`.++## Original adoption checks++Executed with Node 22.23.2, npm 10.9.8 on macOS (CI's supported Node environment should also run its normal checks):++- `npm run lint`: passed, **0 errors / 351 warnings** (347 existing + 4 new genuine findings).+- `npm run build`: passed.+- `npm run build:lib`: passed.+- `npm test -- --maxWorkers=2`: **733 files passed / 1 failed; 7,718 tests passed / 1 failed / 7 todo**. The existing `DeleteProfileModal > calls deleteProfile and shows success toast on successful delete` assertion expected a success-toast call but observed zero. No runtime source changed in this branch. Rerunning that file alone passed all 12 tests; the full-suite failure remains disclosed.+- Initial sandboxed test attempt was stopped because launcher tests could not bind local ports. Results above are from the rerun with port access.++The pinned rule delegates some missing color-token diagnostics to `no-raw-colors`; it is not a complete missing-token guard, nor does it detect the semantic `text-base` collision. Other rules retain their original settings.++This directory is PR-only evidence. Fork PRs require manual `.pr/` cleanup before merge.++## Warning cleanup checks++- `node .pr/verify-inert-classes.mjs`: passed; merged valid classes and compiled CSS are identical for all removals.+- `node .pr/verify-unknown-classes.mjs`: passed; valid theme/plugin utilities and exact selector exceptions accepted while typos remain reported.+- `npm run lint`: passed, **0 unknown-class warnings / 347 existing arbitrary-value warnings / 0 errors**; formatting and TypeScript checks passed.+- `npx vitest run __tests__/components/features/home/repo-selection-form.test.tsx __tests__/components/features/home/workspace-selection-form.test.tsx __tests__/components/features/home/git-repo-dropdown.test.tsx __tests__/components/features/home/workspace-dropdown.test.tsx __tests__/utils/form-control-classes.test.ts --maxWorkers=2`: **5 files / 69 tests passed**.+- `npm run build` and `npm run build:lib`: passed.+- No visual change is claimed: the removed classes have no styling or selector consumers, and the compiled CSS comparison above is identical. The PR also includes real-app workspace screenshots to satisfy frontend evidence CI; they are a smoke comparison, not pixel-diff coverage of every component.+- The original PR head passed Ubuntu and Windows test/build CI. The checks above disclose the earlier local full-suite flake; no new tests or weakened assertions were introduced for inert class removal.++### Real-app screenshot setup++`PATH=/opt/homebrew/opt/node@22/bin:$PATH VITE_DO_NOT_TRACK=1 npm run dev:mock -- --host 127.0.0.1 --port 3196 --strictPort`++Open Workspace in the real Canvas UI using MSW data. `workspace-before.png` uses the four affected source files from `0bfdebb`; `workspace-after.png` uses `a35e74e`. The same running app applied the revisions through Vite HMR. No live LLM or credentials were used. The workspace field and its shared caret retain their appearance; compiler/merge parity covers all four removals.++## Error-level enforcement after updating from main++Merged upstream main at `35dc8aafaad2d883cf0c6629dea857eb2235895e` following [review 5297880470](https://github.com/OpenHands/OpenHands/pull/17644#pullrequestreview-5297880470). With the initial findings resolved, `shadcn/no-unknown-classes` is now `error`; both exact exceptions and every other rule setting are unchanged. This supersedes the issue's original warning-level rollout. CI continues to use ordinary `npm run lint`, without a warning-count gate.++Verified on the merged tree with a fresh `npm ci` (Node 22.23.2):++- `npm run lint`: passed, **zero unknown-class findings / zero errors / 376 existing `shadcn/no-arbitrary-values` warnings**. TypeScript and formatting checks also passed.+- `node .pr/verify-unknown-classes.mjs`: passed; each deliberately invalid utility/variant is severity 2, representative project/plugin utilities are accepted, and exceptions remain exact.+- Real CLI negative check: created a temporary `src/ui/lint-rule-probe-*.tsx` containing `export const Probe = () => <div className="hovr:flex" />;`, ran `node node_modules/eslint/bin/eslint.js <file> --format json`, then removed the file in `finally`. **Exit 1**, exactly one error, from `shadcn/no-unknown-classes`; no parser/fatal error. The earlier stdin attempt was unsuitable for the project-aware parser, so the final check used an actual source file.+- `node .pr/verify-inert-classes.mjs`: passed; the merged theme still generates identical CSS for the removals.+- The five form/dropdown/helper test files listed above: **70 tests passed** on current main.+- `npm run build` and `npm run build:lib`: passed.++Full-suite CI will rerun on the pushed merge. The historical checks above refer to earlier heads; no new full-suite local result is claimed here.diff --git a/.pr/verify-inert-classes.mjs b/.pr/verify-inert-classes.mjsnew file mode 100644index 0000000000..5bbda09eaa--- /dev/null+++ b/.pr/verify-inert-classes.mjs@@ -0,0 +1,38 @@+import assert from "node:assert/strict";+import { readFileSync } from "node:fs";+import { resolve } from "node:path";+import { compile } from "@tailwindcss/node";+import { twMerge } from "tailwind-merge";++// PR-only evidence: run from the repository root with installed dependencies.+// These are the affected elements' class combinations, including the shared+// caret transition helper. Removal must not resurrect a merged-away utility.+const pairs = [+ ["drag-over-content", ""],+ ["relative max-w-auto", "relative"],+ [+ "transition-[transform] ease duration-75 motion-reduce:transition-none",+ "transition-[transform] duration-75 motion-reduce:transition-none",+ ],+];+const stylesheet = readFileSync("src/tailwind.css", "utf8");+async function css(classes) {+ const compiler = await compile(stylesheet, {+ base: resolve("src"),+ onDependency() {},+ });+ return compiler.build(twMerge(classes).split(/\s+/).filter(Boolean));+}+for (const [before, after] of pairs) {+ assert.equal(await css(before), await css(after));+ assert.equal(+ twMerge(before)+ .split(/\s+/)+ .filter((c) => !["drag-over-content", "max-w-auto", "ease"].includes(c))+ .join(" "),+ twMerge(after),+ );+}+console.log(+ "PASS: merged valid classes and compiled CSS are identical for all removals.",+);diff --git a/.pr/verify-unknown-classes.mjs b/.pr/verify-unknown-classes.mjsnew file mode 100644index 0000000000..3fca1842ed--- /dev/null+++ b/.pr/verify-unknown-classes.mjs@@ -0,0 +1,47 @@+import assert from "node:assert/strict";+import { ESLint } from "eslint";++// Run from the repository root: node .pr/verify-unknown-classes.mjs+// Use the real flat config and theme, but let lintText accept a virtual TSX file.+const eslint = new ESLint({+ overrideConfig: [+ {+ languageOptions: { parserOptions: { project: null } },+ rules: { "@typescript-eslint/prefer-optional-chain": "off" },+ },+ ],+});+const classes = [+ "hovr:flex",+ "flex-cols", // Deliberate mistakes; also detect grammar fallback.+ "bg-surface-raised",+ "border-border-input",+ "ring-focus", // Canvas theme.+ "prose",+ "scrollbar-hide",+ "data-[hover=true]:bg-default-100", // Plugins.+ "environment-switch-overlay",+ "conversation-overview-diffs-git-action", // Exceptions.+ "environment-switch-overla", // A nearby typo must still be reported.+];+const [result] = await eslint.lintText(+ `export const probe = <div className="${classes.join(" ")}" />;`,+ { filePath: "src/ui/lint-probe.tsx" },+);+assert.equal(result.fatalErrorCount, 0);+const findings = result.messages.filter(+ (m) => m.ruleId === "shadcn/no-unknown-classes",+);+assert.deepEqual(findings.map((m) => m.message.match(/^"([^"]+)"/)[1]).sort(), [+ "environment-switch-overla",+ "flex-cols",+ "hovr:flex",+]);+for (const finding of findings) {+ assert.equal(finding.severity, 2);+ console.log(finding.message);+}++console.log(+ "PASS: real theme/plugins accepted; typos are errors; exceptions stay exact.",+);diff --git a/.pr/workspace-after.png b/.pr/workspace-after.pngnew file mode 100644index 0000000000..149a0d868bBinary files /dev/null and b/.pr/workspace-after.png differdiff --git a/.pr/workspace-before.png b/.pr/workspace-before.pngnew file mode 100644index 0000000000..9236b6fa4aBinary files /dev/null and b/.pr/workspace-before.png differdiff --git a/eslint.config.js b/eslint.config.jsindex ef1c4080fd..4f0f137f72 100644--- a/eslint.config.js+++ b/eslint.config.js@@ -395,7 +395,8 @@ export default [// Rules: https://github.com/shadcn-ui/lint#rules// `no-arbitrary-values` stays at "warn": the remaining hits are one-offs// (raw hex, vh/vw, calc(), grid templates) with no theme-scale equivalent.- // The other rules need per-component contracts before they are useful here.+ // Class existence does not need component contracts. With no remaining+ // unknown utilities, new findings fail lint; styling policy remains opt-in.{files: ["src/**/*.{ts,tsx}"],plugins: { shadcn: shadcnPlugin },@@ -405,7 +406,17 @@ export default ["shadcn/no-raw-colors": "off","shadcn/no-inline-styles": "off","shadcn/require-static-classes": "off",- "shadcn/no-unknown-classes": "off",+ "shadcn/no-unknown-classes": [+ "error",+ {+ allow: [+ // src/index.css owns the overlay animation outside the theme graph.+ "environment-switch-overlay",+ // Selector target for has-[.conversation-overview-diffs-git-action:hover].+ "conversation-overview-diffs-git-action",+ ],+ },+ ],},},];diff --git a/src/components/features/chat/drag-over.tsx b/src/components/features/chat/drag-over.tsxindex 60695ad2cf..90dc5030c5 100644--- a/src/components/features/chat/drag-over.tsx+++ b/src/components/features/chat/drag-over.tsx@@ -21,7 +21,7 @@ export function DragOver() {className="absolute top-[-16px] left-[-20px]"/></div>- <div className="drag-over-content">+ <div><p>{t(I18nKey.COMMON$DROP_YOUR_FILES_HERE)}</p></div></div>diff --git a/src/components/features/home/repo-selection-form.tsx b/src/components/features/home/repo-selection-form.tsxindex ea95086e79..fd0f523495 100644--- a/src/components/features/home/repo-selection-form.tsx+++ b/src/components/features/home/repo-selection-form.tsx@@ -151,7 +151,6 @@ export function RepositorySelectionForm({placeholder="user/repo"disabled={!selectedProvider || isLoadingSettings}onChange={handleRepoSelection}- className="max-w-auto"/>);};diff --git a/src/components/features/home/workspace-selection-form.tsx b/src/components/features/home/workspace-selection-form.tsxindex 860b60c1f3..a785067f04 100644--- a/src/components/features/home/workspace-selection-form.tsx+++ b/src/components/features/home/workspace-selection-form.tsx@@ -204,7 +204,6 @@ export function WorkspaceSelectionForm({onChange={handleWorkspaceChange}onAddClick={() => setIsBrowserOpen(true)}onManageClick={() => setIsManageOpen(true)}- className="max-w-auto"key={selectedWorkspace?.path ?? "empty-workspace-selection"}/>diff --git a/src/utils/form-control-classes.ts b/src/utils/form-control-classes.tsindex 6138fc74c5..f9bade75af 100644--- a/src/utils/form-control-classes.ts+++ b/src/utils/form-control-classes.ts@@ -36,7 +36,7 @@ export const formControlHeroUiWrapperTransitionClassName = cn(/** Transform-only transitions (e.g. combobox carets). */export const formControlTransformTransitionClassName = cn(- "transition-[transform] ease",+ "transition-[transform]",formControlTransitionDurationClassName,formControlMotionReduceClassName,);