@erclx/canon 5.37.0 → 5.38.0

package/tooling/web/reference.md

@@ -4,13 +4,13 @@
 
 ## Overview
 
-The web layer covers web-universal tooling shared across Vite + React, Astro, and any future web stack. It ships golden configs for ESLint, Vitest, Playwright, Tailwind v4, screenshots, VS Code integration, and CI. Framework-specific wiring (Vite plugins, Astro islands, Next.js config) lives in per-stack adapter folders that extend this layer.
+The web layer covers web-universal tooling shared across Vite + React, Astro, and any future web stack. It ships golden configs for oxlint, Vitest, Playwright, Tailwind v4, screenshots, VS Code integration, and CI. Framework-specific wiring (Vite plugins, Astro islands, Next.js config) lives in per-stack adapter folders that extend this layer.
 
 ## What ships as golden configs
 
 Golden config files live in `tooling/web/configs/` and are copied into the target on `canon tooling sync web . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
-- `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
+- `.oxlintrc.json`: migrated from the ESLint config it replaced. Runs the recommended JS and TypeScript rules, the React hooks and refresh rules, test-scoped vitest rules plus `no-focused-tests`, and `check-file` and `simple-import-sort` as JS plugins.
 - `src/test/setup.ts`: `@testing-library/jest-dom/vitest` import, `cleanup` after each test.
 - `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
@@ -54,9 +54,8 @@ Two worktrees of one repository run the same stack, so a fixed port makes the se
 
 Sticky negative knowledge. Do not relearn.
 
-- Do NOT use `tsc -b` in a Vite project. Composite mode emits `.js` next to `.ts` and ESLint lints the emitted files. Use `tsc --noEmit`.
-- Do NOT accept `eslint@^10` alongside `typescript-eslint@^8`. Chain breaks with `TypeError: Class extends value undefined` from `LegacyESLint`. Pin `eslint@^9` until `typescript-eslint@^9` with ESLint 10 support ships.
-- Do NOT trust `vite-react`'s scaffolded `lint` script. It ships its own `"lint": "oxlint"` under a bare `.oxlintrc.json`, which runs a different rule set from the stack's ESLint config and never gates on it. `[scripts.override]` forces the stack's own eslint invocation back over it.
+- Do NOT use `tsc -b` in a Vite project. Composite mode emits `.js` next to `.ts` and the linter lints the emitted files. Use `tsc --noEmit`.
+- Do NOT trust `vite-react`'s scaffolded `lint` script. It ships a bare `"lint": "oxlint"`, which exits 0 on warnings. `[scripts.override]` forces `--max-warnings 0` over it, and the golden `.oxlintrc.json` overwrites the scaffold's bare one.
 - Do NOT rely on bare-folder exclude globs like `exclude: ["e2e"]`. Use `"e2e/**/*"`.
 - Do NOT ship Vitest with no-tests-fail. Fresh scaffolds have zero tests. Use `passWithNoTests: true` or equivalent until the project has at least one test.
 - Do NOT put Playwright `trace` at the top level of `defineConfig`. It lives under `use`.
@@ -68,17 +67,18 @@ Sticky negative knowledge. Do not relearn.
 - Unit tests: Vitest with jsdom, globals on, setup file at `src/test/setup.ts`, `@testing-library/react`, `@testing-library/user-event`.
 - E2E: Playwright in `e2e/`. Chromium-only for Chrome extensions, all browsers for web apps.
 - Tailwind: v4 via `@tailwindcss/vite`. Never the v3 integration.
-- Prettier: `prettier-plugin-tailwindcss` last in plugins array. Astro also adds `prettier-plugin-astro` first.
+- Lint: oxlint at an exact pin, since its JS plugin host is alpha and a minor release could break `check-file` or `simple-import-sort`. Astro keeps ESLint, which its own reference covers.
 
-## Prettier (extend)
+## oxlint
 
-- Base ships `.prettierrc` with `semi: false`, `singleQuote: true`. Web layer adds `jsxSingleQuote: true` and `prettier-plugin-tailwindcss` via the manifest.
-- Per-stack overrides go in the stack's configs (Astro adds `prettier-plugin-astro` and the `.astro` parser override).
+- Set `lint` and `lint:fix` through `[scripts.override]`, so an already-synced target stops running ESLint on its next sync.
+- Delete a leftover `eslint.config.js` or `eslint.config.mjs`, and `bun remove` the ESLint packages this stack stopped shipping, by hand after that sync. Sync deletes nothing a stack stopped shipping.
+- Keep import sorting on `simple-import-sort` rather than oxfmt's built-in sort, which orders imports differently and would rewrite every import block.
 
 ## lint-staged (extend)
 
-- Add `**/*.{js,jsx,ts,tsx}` glob running `eslint --fix --max-warnings 0`, and `prettier --write`.
-- Extend the prettier glob to include `css`: `**/*.{json,css,md,mdc}`.
+- Add `**/*.{js,jsx,ts,tsx}` glob running `oxlint --fix --max-warnings 0`, and `oxfmt --no-error-on-unmatched-pattern`.
+- Extend the oxfmt glob to include `css`: `**/*.{json,css,md}`.
 
 ## CI docs (extend)
 
@@ -87,7 +87,7 @@ Extend `canon/context/ci.md` so the `## Checks` table reflects the web jobs. <!-
 Append rows:
 
 | Typecheck | `bun run typecheck` | framework-specific typecheck passes |
-| Lint | `bun run lint` | ESLint passes with zero warnings |
+| Lint | `bun run lint` | oxlint passes with zero warnings |
 | Tests | `bun run test:coverage` | Vitest passes with coverage thresholds |
 | Build | `bun run build` | Production build succeeds |
 | E2E | `bun run test:e2e` | Playwright passes against the built preview |
@@ -100,8 +100,8 @@ Extend the `development` context entry under `canon/context/` so the `## Scripts
 
 Append rows:
 
-| `bun run lint` | Run ESLint with zero warnings allowed. |
-| `bun run lint:fix` | Auto-fix ESLint issues. |
+| `bun run lint` | Run oxlint with zero warnings allowed. |
+| `bun run lint:fix` | Auto-fix oxlint issues. |
 | `bun run test` | Run Vitest in watch mode. |
 | `bun run test:run` | Run Vitest once with verbose reporter. |
 | `bun run test:coverage` | Run Vitest with coverage. |

package/tooling/base/configs/.prettierrc

@@ -1,12 +0,0 @@
-{
-  "semi": false,
-  "singleQuote": true,
-  "overrides": [
-    {
-      "files": "*.mdc",
-      "options": {
-        "parser": "markdown"
-      }
-    }
-  ]
-}

package/tooling/nextjs/configs/eslint.config.js

@@ -1,91 +0,0 @@
-import js from '@eslint/js'
-import { defineConfig, globalIgnores } from 'eslint/config'
-import prettier from 'eslint-config-prettier'
-import checkFile from 'eslint-plugin-check-file'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import simpleImportSort from 'eslint-plugin-simple-import-sort'
-import vitest from 'eslint-plugin-vitest'
-import globals from 'globals'
-import tseslint from 'typescript-eslint'
-
-export default defineConfig([
-  globalIgnores([
-    '.next',
-    'next-env.d.ts',
-    'dist',
-    'dist-ssr',
-    'coverage',
-    'release',
-    '.claude',
-    '.vscode',
-    '.husky',
-    'test-results',
-    'playwright-report',
-    'blob-report',
-    'playwright/.cache',
-  ]),
-  js.configs.recommended,
-  ...tseslint.configs.recommended,
-  {
-    files: ['**/*.{ts,tsx,js,jsx}'],
-    plugins: {
-      'react-hooks': reactHooks,
-      'react-refresh': reactRefresh,
-      'simple-import-sort': simpleImportSort,
-      'check-file': checkFile,
-    },
-    languageOptions: {
-      globals: {
-        ...globals.browser,
-      },
-    },
-    rules: {
-      ...reactHooks.configs.recommended.rules,
-      'react-refresh/only-export-components': [
-        'warn',
-        { allowConstantExport: true },
-      ],
-      'simple-import-sort/imports': 'error',
-      'simple-import-sort/exports': 'error',
-      '@typescript-eslint/no-unused-vars': [
-        'error',
-        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
-      ],
-      'check-file/filename-naming-convention': [
-        'error',
-        { '**/*.{ts,tsx}': 'KEBAB_CASE' },
-        { ignoreMiddleExtensions: true },
-      ],
-      'check-file/folder-naming-convention': [
-        'error',
-        { 'src/**/!(__tests__)/': 'KEBAB_CASE' },
-      ],
-    },
-  },
-  {
-    // App Router route and layout files export non-component values (metadata, route handlers) and use bracket, paren, and at-sign folder syntax (dynamic segments, route groups, parallel slots), which these rules flag as violations.
-    files: ['src/app/**/*.{ts,tsx}'],
-    rules: {
-      'react-refresh/only-export-components': 'off',
-      'check-file/folder-naming-convention': 'off',
-    },
-  },
-  {
-    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
-    ...vitest.configs.recommended,
-  },
-  {
-    files: [
-      '*.config.{js,mjs,cjs,ts}',
-      'vitest.config.ts',
-      'playwright.config.ts',
-    ],
-    languageOptions: {
-      globals: {
-        ...globals.node,
-      },
-    },
-  },
-  prettier,
-])

package/tooling/web/configs/eslint.config.js

@@ -1,82 +0,0 @@
-import js from '@eslint/js'
-import { defineConfig, globalIgnores } from 'eslint/config'
-import prettier from 'eslint-config-prettier'
-import checkFile from 'eslint-plugin-check-file'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import simpleImportSort from 'eslint-plugin-simple-import-sort'
-import vitest from 'eslint-plugin-vitest'
-import globals from 'globals'
-import tseslint from 'typescript-eslint'
-
-export default defineConfig([
-  globalIgnores([
-    'dist',
-    'dist-ssr',
-    'coverage',
-    'release',
-    '.claude',
-    '.vscode',
-    '.husky',
-    'test-results',
-    'playwright-report',
-    'blob-report',
-    'playwright/.cache',
-  ]),
-  js.configs.recommended,
-  ...tseslint.configs.recommended,
-  {
-    files: ['**/*.{ts,tsx,js,jsx}'],
-    plugins: {
-      'react-hooks': reactHooks,
-      'react-refresh': reactRefresh,
-      'simple-import-sort': simpleImportSort,
-      'check-file': checkFile,
-    },
-    languageOptions: {
-      globals: {
-        ...globals.browser,
-      },
-    },
-    rules: {
-      ...reactHooks.configs.recommended.rules,
-      'react-refresh/only-export-components': [
-        'warn',
-        { allowConstantExport: true },
-      ],
-      'simple-import-sort/imports': 'error',
-      'simple-import-sort/exports': 'error',
-      '@typescript-eslint/no-unused-vars': [
-        'error',
-        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
-      ],
-      'check-file/filename-naming-convention': [
-        'error',
-        { '**/!(App).{ts,tsx}': 'KEBAB_CASE' },
-        { ignoreMiddleExtensions: true },
-      ],
-      'check-file/folder-naming-convention': [
-        'error',
-        { 'src/**/!(__tests__)/': 'KEBAB_CASE' },
-      ],
-    },
-  },
-  {
-    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
-    ...vitest.configs.recommended,
-  },
-  {
-    files: [
-      '*.config.{js,mjs,cjs,ts}',
-      'vite.config.ts',
-      'vitest.config.ts',
-      'playwright.config.ts',
-    ],
-    languageOptions: {
-      globals: {
-        ...globals.node,
-      },
-    },
-  },
-  prettier,
-])