From e64f65642ffcf5348c652ebabe609f0f8fde69ea Mon Sep 17 00:00:00 2001 From: Amritanshu Date: Tue, 22 Sep 2026 23:15:08 +0530 Subject: [PATCH] Add ESLint and Prettier Prettier owns formatting: .prettierrc.json, format and format:check scripts, and a one-off pass over the repo so the check is green from the start. Embedded language formatting is off deliberately - the renderers build HTML in html tagged templates and letting Prettier reflow those would change the markup customers receive. docs/ is excluded because it is hand-wrapped prose, and shell scripts have no Prettier parser. ESLint covers the JavaScript: the two browser scripts, the build and check scripts, and its own config. no-var is scoped out for the browser scripts on purpose; they are plain ES5-shaped IIFEs and a hoisting difference would only show up in a browser. ESLint cannot lint the TypeScript here: typescript@7 is the native port with no JavaScript compiler API, and typescript-eslint requires a 4.8-6.1 peer, so it refuses to install and forcing it through would leave a parser that cannot read the compiler. tsc --noEmit stays the TypeScript gate; README records the two ways to change that. lint and format:check now run in deploy.sh, and VS Code formats on save with Prettier and surfaces ESLint findings. --- .prettierignore | 9 + .prettierrc.json | 8 + .vscode/extensions.json | 3 + .vscode/settings.json | 4 +- .vscode/tasks.json | 22 +- README.md | 40 +- compose.yaml | 4 +- deploy.sh | 6 +- eslint.config.js | 56 +++ package-lock.json | 964 ++++++++++++++++++++++++++++++++++++++++ package.json | 8 + public/app.js | 1 - public/styles.css | 14 +- scripts/check-dnd.mjs | 4 +- scripts/check-site.ts | 7 +- scripts/seed-dev.ts | 37 +- src/auth.ts | 19 +- src/config.ts | 11 +- src/images/pipeline.ts | 4 +- src/render/admin.ts | 94 ++-- src/render/layout.ts | 8 +- src/render/pages.ts | 48 +- src/routes/admin.ts | 21 +- src/routes/public.ts | 17 +- src/server.ts | 3 +- src/storage/identity.ts | 6 +- src/storage/manifest.ts | 3 +- src/storage/repair.ts | 4 +- src/storage/sections.ts | 12 +- src/storage/sets.ts | 14 +- src/storage/validate.ts | 15 +- test/admin.test.ts | 53 ++- test/auth.test.ts | 14 +- test/config.test.ts | 7 +- test/identity.test.ts | 33 +- test/pipeline.test.ts | 8 +- test/repair.test.ts | 5 +- test/routes.test.ts | 21 +- test/sets.test.ts | 25 +- test/validate.test.ts | 9 +- 40 files changed, 1469 insertions(+), 172 deletions(-) create mode 100644 .prettierignore create mode 100644 .prettierrc.json create mode 100644 .vscode/extensions.json create mode 100644 eslint.config.js 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