diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..cc7c83c --- /dev/null +++ b/.prettierignore @@ -0,0 +1,9 @@ +node_modules +.dev +.tmp +.npm-cache +public/fonts +public/prototype +docs/design +package-lock.json +docs diff --git a/.prettierrc.json b/.prettierrc.json new file mode 100644 index 0000000..3072a5b --- /dev/null +++ b/.prettierrc.json @@ -0,0 +1,8 @@ +{ + "singleQuote": true, + "semi": true, + "printWidth": 100, + "trailingComma": "all", + "arrowParens": "always", + "embeddedLanguageFormatting": "off" +} diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..d7df89c --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,3 @@ +{ + "recommendations": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"] +} diff --git a/.vscode/settings.json b/.vscode/settings.json index 3ecef2d..cf03562 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -19,5 +19,7 @@ "editor.insertSpaces": true, "files.eol": "\n", "files.trimTrailingWhitespace": true, - "files.insertFinalNewline": true + "files.insertFinalNewline": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index b0382d8..1085401 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -7,6 +7,18 @@ "script": "dev:env", "problemMatcher": [] }, + { + "label": "format", + "type": "npm", + "script": "format", + "problemMatcher": [] + }, + { + "label": "lint", + "type": "npm", + "script": "lint", + "problemMatcher": ["$eslint-stylish"] + }, { "label": "dev: seed placeholder menus", "type": "npm", @@ -23,14 +35,20 @@ "label": "test", "type": "npm", "script": "test", - "group": { "kind": "test", "isDefault": true }, + "group": { + "kind": "test", + "isDefault": true + }, "problemMatcher": [] }, { "label": "typecheck", "type": "npm", "script": "typecheck", - "group": { "kind": "build", "isDefault": true }, + "group": { + "kind": "build", + "isDefault": true + }, "problemMatcher": ["$tsc"] }, { diff --git a/README.md b/README.md index 20ac6c0..d5ec9b6 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,32 @@ npm run verify # integrity of .dev/data npm run check-site -- http://127.0.0.1:3000 # checks a running site from outside ``` +### Linting and formatting + +```sh +npm run lint # eslint +npm run lint:fix +npm run format # prettier --write +npm run format:check # what CI and deploy.sh run +``` + +Prettier owns formatting (`.prettierrc.json`); `docs/` is excluded because those +are hand-wrapped notes rather than code. `embeddedLanguageFormatting` is off on +purpose: the renderers build HTML inside `html` tagged template literals, and +letting Prettier reflow those would change the markup customers receive. + +**ESLint does not lint the TypeScript, and cannot as things stand.** This project +uses the native TypeScript port (`typescript@7`), which ships no JavaScript +compiler API — and every ESLint TypeScript parser needs one. `typescript-eslint` +declares `typescript >=4.8.4 <6.1.0` as a peer and refuses to install; forcing it +through would leave a parser that cannot read the compiler it was given. The +TypeScript gate is therefore `npm run typecheck` (strict, with `noUnusedLocals`, +`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes` and +`erasableSyntaxOnly`), and ESLint covers the JavaScript. To get ESLint over the +`.ts` files as well, either pin `typescript@5.9` — which supports everything this +project uses — and add `typescript-eslint`, or add `oxlint`, which parses +TypeScript without the compiler API. + Dragging Pages is the one interaction that only a browser can check, so there is a harness for it. It needs `geckodriver` on PATH and a running dev server: @@ -98,18 +124,18 @@ npm run check-dnd -- none # just reports affordances `.vscode/` holds launch configurations and tasks. -| Configuration | What it does | -| --- | --- | -| **Dev server (debug)** | runs `src/server.ts` with the dev environment, breakpoints live | -| **Dev server (watch, no debugger)** | `npm run dev` in a terminal | -| **Debug the open test file** | runs the file you have open under `node --test`, with child processes attached so breakpoints inside a test bind | -| **Check the running site** | prompts for a URL and runs `scripts/check-site.ts` | +| Configuration | What it does | +| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **Dev server (debug)** | runs `src/server.ts` with the dev environment, breakpoints live | +| **Dev server (watch, no debugger)** | `npm run dev` in a terminal | +| **Debug the open test file** | runs the file you have open under `node --test`, with child processes attached so breakpoints inside a test bind | +| **Check the running site** | prompts for a URL and runs `scripts/check-site.ts` | Breakpoints land in the `.ts` files themselves: Node strips types in place, so line numbers are the ones you see. The debug configuration creates `.dev/site.env` first (`preLaunchTask`), so a fresh clone serves a working admin immediately. -Tasks (Command Palette → *Run Task*) cover the same ground: seed, the dev server, +Tasks (Command Palette → _Run Task_) cover the same ground: seed, the dev server, tests, typecheck, verify and repair. `.dev`, `.tmp` and `.npm-cache` are hidden from the explorer, search and the file watcher, so a watched server does not restart on its own data writes. diff --git a/compose.yaml b/compose.yaml index 4df6001..e91b801 100644 --- a/compose.yaml +++ b/compose.yaml @@ -7,11 +7,11 @@ services: build: . image: menu-admin:dev ports: - - "3000:3000" + - '3000:3000' environment: MENU_ROOT: /data MENU_SITE_CONFIG: /etc/menu-app/site.json - SECURE_COOKIES: "false" + SECURE_COOKIES: 'false' LOG_LEVEL: info volumes: - ./config/hopsngrains.site.json:/etc/menu-app/site.json:ro diff --git a/deploy.sh b/deploy.sh index b1d64fe..930be55 100755 --- a/deploy.sh +++ b/deploy.sh @@ -20,9 +20,11 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cd "$ROOT" if [[ -z "${SKIP_TESTS:-}" ]]; then - echo "==> tests" - npm test + echo "==> lint, format and tests" + npm run lint + npm run format:check npm run typecheck + npm test fi echo "==> building ${IMAGE}" diff --git a/eslint.config.js b/eslint.config.js new file mode 100644 index 0000000..a8c1a92 --- /dev/null +++ b/eslint.config.js @@ -0,0 +1,56 @@ +// ESLint, flat config. Lints the JavaScript: the two browser scripts the menus +// and the admin actually run, the build and check scripts, and this file. +// +// TypeScript is deliberately not linted here. The project's TypeScript is the +// native port (typescript@7), which ships no JavaScript compiler API, and every +// ESLint TypeScript parser needs one — typescript-eslint requires +// `typescript >=4.8.4 <6.1.0` and refuses to install. `npm run typecheck` +// (tsc --noEmit, strict, with noUnusedLocals, noUncheckedIndexedAccess, +// exactOptionalPropertyTypes and erasableSyntaxOnly) is the TypeScript gate. +// See README.md for the two ways to put ESLint on the .ts files as well. + +import js from '@eslint/js'; +import globals from 'globals'; + +export default [ + { + ignores: [ + 'node_modules/**', + '.dev/**', + '.tmp/**', + '.npm-cache/**', + 'public/fonts/**', + 'public/prototype/**', + 'docs/design/**', + ], + }, + js.configs.recommended, + { + // The browser scripts: old-fashioned IIFEs loaded with a plain