From e5220bc18119bc1cc3bf73f036d58228312c2882 Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:32:25 +0300 Subject: [PATCH 1/2] build: every version lives in the workspace's catalog, and the checks read every package ADR-0018, step 1 (decision 4). The 51 versions move from package.json into the catalog of pnpm-workspace.yaml, and package.json names each as "catalog:". No version changes: every catalog entry of the lockfile resolves to exactly its version, and the install fetched nothing. - scripts/pins.ts reads the workspace (scripts/workspace.ts, line by line, refusing a shape it does not read) and every package of it: a package takes its versions from the catalog or from the workspace, the catalog holds exact stable versions, a 0.x one needs its dated exception. - pinExceptions stays in the root package.json: a pnpm the project pins refuses a setting it does not know in pnpm-workspace.yaml (ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS). - pnpm static licences lists every package (-r); without it pnpm lists the root's dependencies alone. - Biome turns a domain of rules on by itself only for a dependency with a version, so with "catalog:" six domains went quiet. biome.json names them, and pnpm static schemas keeps them in step with the catalog, and reads Biome's version from it. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- biome.json | 8 + package.json | 102 +++++------ pnpm-lock.yaml | 258 +++++++++++++++++++++------ pnpm-workspace.yaml | 55 ++++++ scripts/check-static.ts | 10 +- scripts/checks/licences.ts | 22 ++- scripts/checks/schemas.ts | 95 ++++++++-- scripts/pins.ts | 110 ++++++++---- scripts/workspace.ts | 110 ++++++++++++ test/unit/licences-workspace.test.ts | 60 +++++++ test/unit/pins.test.ts | 140 +++++++++++++-- test/unit/schemas.test.ts | 39 +++- 12 files changed, 821 insertions(+), 188 deletions(-) create mode 100644 scripts/workspace.ts create mode 100644 test/unit/licences-workspace.test.ts diff --git a/biome.json b/biome.json index 7bfc40c..5d70607 100644 --- a/biome.json +++ b/biome.json @@ -34,6 +34,14 @@ "style": { "noNonNullAssertion": "error" } + }, + "domains": { + "drizzle": "recommended", + "playwright": "recommended", + "react": "recommended", + "tailwind": "recommended", + "tanstackQuery": "recommended", + "test": "recommended" } }, "javascript": { diff --git a/package.json b/package.json index 1e5f8da..84f15e9 100644 --- a/package.json +++ b/package.json @@ -32,59 +32,59 @@ "auth:ddl": "node scripts/auth-ddl.ts --check" }, "dependencies": { - "@ai-sdk/provider": "4.0.38", - "@ai-sdk/react": "4.0.177", - "@better-auth/passkey": "1.7.25", - "@cloudflare/ai-chat": "0.12.2", - "@cloudflare/kumo": "2.18.1", - "@modelcontextprotocol/sdk": "1.32.2", - "@modelcontextprotocol/server": "2.4.0", - "@phosphor-icons/react": "2.1.10", - "@tanstack/react-query": "5.107.1", - "@tanstack/react-router": "1.170.46", - "@tiptap/extension-color": "3.34.0", - "@tiptap/extension-highlight": "3.34.0", - "@tiptap/extension-image": "3.34.0", - "@tiptap/extension-link": "3.34.0", - "@tiptap/extension-text-align": "3.34.0", - "@tiptap/extension-text-style": "3.34.0", - "@tiptap/extension-underline": "3.34.0", - "@tiptap/pm": "3.34.0", - "@tiptap/react": "3.34.0", - "@tiptap/starter-kit": "3.34.0", - "agents": "0.33.0", - "ai": "7.0.173", - "better-auth": "1.7.25", - "dompurify": "3.4.18", - "drizzle-orm": "0.45.4", - "hono": "4.13.18", - "jose": "6.2.17", - "postal-mime": "4.2.1", - "react": "19.3.1", - "react-dom": "19.3.1", - "react-markdown": "10.1.0", - "remark-gfm": "4.0.1", - "uqr": "0.1.3", - "zod": "4.6.7", - "zustand": "5.1.0" + "@ai-sdk/provider": "catalog:", + "@ai-sdk/react": "catalog:", + "@better-auth/passkey": "catalog:", + "@cloudflare/ai-chat": "catalog:", + "@cloudflare/kumo": "catalog:", + "@modelcontextprotocol/sdk": "catalog:", + "@modelcontextprotocol/server": "catalog:", + "@phosphor-icons/react": "catalog:", + "@tanstack/react-query": "catalog:", + "@tanstack/react-router": "catalog:", + "@tiptap/extension-color": "catalog:", + "@tiptap/extension-highlight": "catalog:", + "@tiptap/extension-image": "catalog:", + "@tiptap/extension-link": "catalog:", + "@tiptap/extension-text-align": "catalog:", + "@tiptap/extension-text-style": "catalog:", + "@tiptap/extension-underline": "catalog:", + "@tiptap/pm": "catalog:", + "@tiptap/react": "catalog:", + "@tiptap/starter-kit": "catalog:", + "agents": "catalog:", + "ai": "catalog:", + "better-auth": "catalog:", + "dompurify": "catalog:", + "drizzle-orm": "catalog:", + "hono": "catalog:", + "jose": "catalog:", + "postal-mime": "catalog:", + "react": "catalog:", + "react-dom": "catalog:", + "react-markdown": "catalog:", + "remark-gfm": "catalog:", + "uqr": "catalog:", + "zod": "catalog:", + "zustand": "catalog:" }, "devDependencies": { - "@biomejs/biome": "2.6.8", - "@cloudflare/vite-plugin": "1.69.1", - "@cloudflare/vitest-plugin": "1.8.2", - "@playwright/test": "1.65.1", - "@tailwindcss/vite": "4.3.5", - "@types/jsdom": "30.0.0", - "@types/node": "24.19.2", - "@types/react": "19.3.0", - "@types/react-dom": "19.3.0", - "@vitejs/plugin-react": "6.3.0", - "jsdom": "31.0.1", - "tailwindcss": "4.3.5", - "typescript": "7.0.2", - "vite": "8.3.8", - "vitest": "5.1.0", - "wrangler": "4.162.0" + "@biomejs/biome": "catalog:", + "@cloudflare/vite-plugin": "catalog:", + "@cloudflare/vitest-plugin": "catalog:", + "@playwright/test": "catalog:", + "@tailwindcss/vite": "catalog:", + "@types/jsdom": "catalog:", + "@types/node": "catalog:", + "@types/react": "catalog:", + "@types/react-dom": "catalog:", + "@vitejs/plugin-react": "catalog:", + "jsdom": "catalog:", + "tailwindcss": "catalog:", + "typescript": "catalog:", + "vite": "catalog:", + "vitest": "catalog:", + "wrangler": "catalog:" }, "pinExceptions": { "@cloudflare/ai-chat": "2026-11-17: 0.x, no stable release exists; the agent is optional and off by default", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7c68c68..72e920d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -162,163 +162,319 @@ settings: autoInstallPeers: true excludeLinksFromLockfile: false +catalogs: + default: + '@ai-sdk/provider': + specifier: 4.0.38 + version: 4.0.38 + '@ai-sdk/react': + specifier: 4.0.177 + version: 4.0.177 + '@better-auth/passkey': + specifier: 1.7.25 + version: 1.7.25 + '@biomejs/biome': + specifier: 2.6.8 + version: 2.6.8 + '@cloudflare/ai-chat': + specifier: 0.12.2 + version: 0.12.2 + '@cloudflare/kumo': + specifier: 2.18.1 + version: 2.18.1 + '@cloudflare/vite-plugin': + specifier: 1.69.1 + version: 1.69.1 + '@cloudflare/vitest-plugin': + specifier: 1.8.2 + version: 1.8.2 + '@modelcontextprotocol/sdk': + specifier: 1.32.2 + version: 1.32.2 + '@modelcontextprotocol/server': + specifier: 2.4.0 + version: 2.4.0 + '@phosphor-icons/react': + specifier: 2.1.10 + version: 2.1.10 + '@playwright/test': + specifier: 1.65.1 + version: 1.65.1 + '@tailwindcss/vite': + specifier: 4.3.5 + version: 4.3.5 + '@tanstack/react-query': + specifier: 5.107.1 + version: 5.107.1 + '@tanstack/react-router': + specifier: 1.170.46 + version: 1.170.46 + '@tiptap/extension-color': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/extension-highlight': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/extension-image': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/extension-link': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/extension-text-align': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/extension-text-style': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/extension-underline': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/pm': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/react': + specifier: 3.34.0 + version: 3.34.0 + '@tiptap/starter-kit': + specifier: 3.34.0 + version: 3.34.0 + '@types/jsdom': + specifier: 30.0.0 + version: 30.0.0 + '@types/node': + specifier: 24.19.2 + version: 24.19.2 + '@types/react': + specifier: 19.3.0 + version: 19.3.0 + '@types/react-dom': + specifier: 19.3.0 + version: 19.3.0 + '@vitejs/plugin-react': + specifier: 6.3.0 + version: 6.3.0 + agents: + specifier: 0.33.0 + version: 0.33.0 + ai: + specifier: 7.0.173 + version: 7.0.173 + better-auth: + specifier: 1.7.25 + version: 1.7.25 + dompurify: + specifier: 3.4.18 + version: 3.4.18 + drizzle-orm: + specifier: 0.45.4 + version: 0.45.4 + hono: + specifier: 4.13.18 + version: 4.13.18 + jose: + specifier: 6.2.17 + version: 6.2.17 + jsdom: + specifier: 31.0.1 + version: 31.0.1 + postal-mime: + specifier: 4.2.1 + version: 4.2.1 + react: + specifier: 19.3.1 + version: 19.3.1 + react-dom: + specifier: 19.3.1 + version: 19.3.1 + react-markdown: + specifier: 10.1.0 + version: 10.1.0 + remark-gfm: + specifier: 4.0.1 + version: 4.0.1 + tailwindcss: + specifier: 4.3.5 + version: 4.3.5 + typescript: + specifier: 7.0.2 + version: 7.0.2 + uqr: + specifier: 0.1.3 + version: 0.1.3 + vite: + specifier: 8.3.8 + version: 8.3.8 + vitest: + specifier: 5.1.0 + version: 5.1.0 + wrangler: + specifier: 4.162.0 + version: 4.162.0 + zod: + specifier: 4.6.7 + version: 4.6.7 + zustand: + specifier: 5.1.0 + version: 5.1.0 + importers: .: dependencies: '@ai-sdk/provider': - specifier: 4.0.38 + specifier: 'catalog:' version: 4.0.38 '@ai-sdk/react': - specifier: 4.0.177 + specifier: 'catalog:' version: 4.0.177(react@19.3.1)(zod@4.6.7) '@better-auth/passkey': - specifier: 1.7.25 + specifier: 'catalog:' version: 1.7.25(@better-auth/core@1.7.25(@better-auth/utils@0.5.1)(@better-fetch/fetch@1.3.3)(@opentelemetry/api@1.10.0)(better-call@1.4.5(zod@4.6.7))(jose@6.2.17)(kysely@0.29.9)(nanostores@1.5.5))(@better-auth/utils@0.5.1)(@better-fetch/fetch@1.3.3)(better-auth@1.7.25(@opentelemetry/api@1.10.0)(drizzle-orm@0.45.4(@opentelemetry/api@1.10.0)(kysely@0.29.9))(react-dom@19.3.1(react@19.3.1))(react@19.3.1)(vitest@5.1.0(@opentelemetry/api@1.10.0)(@types/node@24.19.2)(jsdom@31.0.1(@noble/hashes@2.4.0))(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))))(better-call@1.4.5(zod@4.6.7))(nanostores@1.5.5) '@cloudflare/ai-chat': - specifier: 0.12.2 + specifier: 'catalog:' version: 0.12.2(@ai-sdk/react@4.0.177(react@19.3.1)(zod@4.6.7))(agents@0.33.0(@ai-sdk/provider@4.0.38)(@ai-sdk/react@4.0.177(react@19.3.1)(zod@4.6.7))(@babel/core@8.1.2)(@babel/runtime@8.1.2)(@modelcontextprotocol/client@2.4.0)(@modelcontextprotocol/sdk@1.32.2(@cfworker/json-schema@4.1.6)(supports-color@10.2.2)(zod@4.6.7))(@modelcontextprotocol/server@2.4.0)(ai@7.0.173(zod@4.6.7))(react@19.3.1)(rolldown@1.2.19)(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))(zod@4.6.7))(ai@7.0.173(zod@4.6.7))(react@19.3.1) '@cloudflare/kumo': - specifier: 2.18.1 + specifier: 'catalog:' version: 2.18.1(@date-fns/tz@1.5.0)(@phosphor-icons/react@2.1.10(react-dom@19.3.1(react@19.3.1))(react@19.3.1))(@types/react@19.3.0)(date-fns@4.4.0)(react-dom@19.3.1(react@19.3.1))(react@19.3.1)(zod@4.6.7) '@modelcontextprotocol/sdk': - specifier: 1.32.2 + specifier: 'catalog:' version: 1.32.2(@cfworker/json-schema@4.1.6)(supports-color@10.2.2)(zod@4.6.7) '@modelcontextprotocol/server': - specifier: 2.4.0 + specifier: 'catalog:' version: 2.4.0 '@phosphor-icons/react': - specifier: 2.1.10 + specifier: 'catalog:' version: 2.1.10(react-dom@19.3.1(react@19.3.1))(react@19.3.1) '@tanstack/react-query': - specifier: 5.107.1 + specifier: 'catalog:' version: 5.107.1(@types/react@19.3.0)(react@19.3.1) '@tanstack/react-router': - specifier: 1.170.46 + specifier: 'catalog:' version: 1.170.46(react-dom@19.3.1(react@19.3.1))(react@19.3.1) '@tiptap/extension-color': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/extension-text-style@3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0))) '@tiptap/extension-highlight': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0)) '@tiptap/extension-image': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0)) '@tiptap/extension-link': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0))(@tiptap/pm@3.34.0) '@tiptap/extension-text-align': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0)) '@tiptap/extension-text-style': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0)) '@tiptap/extension-underline': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@tiptap/core@3.34.0(@tiptap/pm@3.34.0)) '@tiptap/pm': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0 '@tiptap/react': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0(@floating-ui/dom@1.8.0)(@tiptap/core@3.34.0(@tiptap/pm@3.34.0))(@tiptap/pm@3.34.0)(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.3.1(react@19.3.1))(react@19.3.1) '@tiptap/starter-kit': - specifier: 3.34.0 + specifier: 'catalog:' version: 3.34.0 agents: - specifier: 0.33.0 + specifier: 'catalog:' version: 0.33.0(@ai-sdk/provider@4.0.38)(@ai-sdk/react@4.0.177(react@19.3.1)(zod@4.6.7))(@babel/core@8.1.2)(@babel/runtime@8.1.2)(@modelcontextprotocol/client@2.4.0)(@modelcontextprotocol/sdk@1.32.2(@cfworker/json-schema@4.1.6)(supports-color@10.2.2)(zod@4.6.7))(@modelcontextprotocol/server@2.4.0)(ai@7.0.173(zod@4.6.7))(react@19.3.1)(rolldown@1.2.19)(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))(zod@4.6.7) ai: - specifier: 7.0.173 + specifier: 'catalog:' version: 7.0.173(zod@4.6.7) better-auth: - specifier: 1.7.25 + specifier: 'catalog:' version: 1.7.25(@opentelemetry/api@1.10.0)(drizzle-orm@0.45.4(@opentelemetry/api@1.10.0)(kysely@0.29.9))(react-dom@19.3.1(react@19.3.1))(react@19.3.1)(vitest@5.1.0(@opentelemetry/api@1.10.0)(@types/node@24.19.2)(jsdom@31.0.1(@noble/hashes@2.4.0))(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))) dompurify: - specifier: 3.4.18 + specifier: 'catalog:' version: 3.4.18 drizzle-orm: - specifier: 0.45.4 + specifier: 'catalog:' version: 0.45.4(@opentelemetry/api@1.10.0)(kysely@0.29.9) hono: - specifier: 4.13.18 + specifier: 'catalog:' version: 4.13.18 jose: - specifier: 6.2.17 + specifier: 'catalog:' version: 6.2.17 postal-mime: - specifier: 4.2.1 + specifier: 'catalog:' version: 4.2.1 react: - specifier: 19.3.1 + specifier: 'catalog:' version: 19.3.1 react-dom: - specifier: 19.3.1 + specifier: 'catalog:' version: 19.3.1(react@19.3.1) react-markdown: - specifier: 10.1.0 + specifier: 'catalog:' version: 10.1.0(@types/react@19.3.0)(react@19.3.1)(supports-color@10.2.2) remark-gfm: - specifier: 4.0.1 + specifier: 'catalog:' version: 4.0.1(supports-color@10.2.2) uqr: - specifier: 0.1.3 + specifier: 'catalog:' version: 0.1.3 zod: - specifier: 4.6.7 + specifier: 'catalog:' version: 4.6.7 zustand: - specifier: 5.1.0 + specifier: 'catalog:' version: 5.1.0(@types/react@19.3.0)(react@19.3.1)(use-sync-external-store@1.7.0(react@19.3.1)) devDependencies: '@biomejs/biome': - specifier: 2.6.8 + specifier: 'catalog:' version: 2.6.8 '@cloudflare/vite-plugin': - specifier: 1.69.1 + specifier: 'catalog:' version: 1.69.1(@types/node@24.19.2)(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))(workerd@1.20261113.1)(wrangler@4.162.0(@types/node@24.19.2)) '@cloudflare/vitest-plugin': - specifier: 1.8.2 + specifier: 'catalog:' version: 1.8.2(@types/node@24.19.2)(vitest@5.1.0(@opentelemetry/api@1.10.0)(@types/node@24.19.2)(jsdom@31.0.1(@noble/hashes@2.4.0))(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))) '@playwright/test': - specifier: 1.65.1 + specifier: 'catalog:' version: 1.65.1 '@tailwindcss/vite': - specifier: 4.3.5 + specifier: 'catalog:' version: 4.3.5(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1)) '@types/jsdom': - specifier: 30.0.0 + specifier: 'catalog:' version: 30.0.0 '@types/node': - specifier: 24.19.2 + specifier: 'catalog:' version: 24.19.2 '@types/react': - specifier: 19.3.0 + specifier: 'catalog:' version: 19.3.0 '@types/react-dom': - specifier: 19.3.0 + specifier: 'catalog:' version: 19.3.0(@types/react@19.3.0) '@vitejs/plugin-react': - specifier: 6.3.0 + specifier: 'catalog:' version: 6.3.0(@rolldown/plugin-babel@0.2.4(@babel/core@8.1.2)(@babel/runtime@8.1.2)(rolldown@1.2.19)(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1)))(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1)) jsdom: - specifier: 31.0.1 + specifier: 'catalog:' version: 31.0.1(@noble/hashes@2.4.0) tailwindcss: - specifier: 4.3.5 + specifier: 'catalog:' version: 4.3.5 typescript: - specifier: 7.0.2 + specifier: 'catalog:' version: 7.0.2 vite: - specifier: 8.3.8 + specifier: 'catalog:' version: 8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1) vitest: - specifier: 5.1.0 + specifier: 'catalog:' version: 5.1.0(@opentelemetry/api@1.10.0)(@types/node@24.19.2)(jsdom@31.0.1(@noble/hashes@2.4.0))(vite@8.3.8(@types/node@24.19.2)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1)) wrangler: - specifier: 4.162.0 + specifier: 'catalog:' version: 4.162.0(@types/node@24.19.2) packages: diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 1965d1e..a0f3d0a 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -11,3 +11,58 @@ allowBuilds: sharp: true # Its script only prints a funding banner. core-js-pure: false + +# V1 (docs/engineering-rules.md, ADR-0018 decision 4): every version of the workspace is written +# here once, exactly; a package names it as "catalog:". scripts/pins.ts holds both. +catalog: + "@ai-sdk/provider": 4.0.38 + "@ai-sdk/react": 4.0.177 + "@better-auth/passkey": 1.7.25 + "@biomejs/biome": 2.6.8 + "@cloudflare/ai-chat": 0.12.2 + "@cloudflare/kumo": 2.18.1 + "@cloudflare/vite-plugin": 1.69.1 + "@cloudflare/vitest-plugin": 1.8.2 + "@modelcontextprotocol/sdk": 1.32.2 + "@modelcontextprotocol/server": 2.4.0 + "@phosphor-icons/react": 2.1.10 + "@playwright/test": 1.65.1 + "@tailwindcss/vite": 4.3.5 + "@tanstack/react-query": 5.107.1 + "@tanstack/react-router": 1.170.46 + "@tiptap/extension-color": 3.34.0 + "@tiptap/extension-highlight": 3.34.0 + "@tiptap/extension-image": 3.34.0 + "@tiptap/extension-link": 3.34.0 + "@tiptap/extension-text-align": 3.34.0 + "@tiptap/extension-text-style": 3.34.0 + "@tiptap/extension-underline": 3.34.0 + "@tiptap/pm": 3.34.0 + "@tiptap/react": 3.34.0 + "@tiptap/starter-kit": 3.34.0 + "@types/jsdom": 30.0.0 + "@types/node": 24.19.2 + "@types/react": 19.3.0 + "@types/react-dom": 19.3.0 + "@vitejs/plugin-react": 6.3.0 + agents: 0.33.0 + ai: 7.0.173 + better-auth: 1.7.25 + dompurify: 3.4.18 + drizzle-orm: 0.45.4 + hono: 4.13.18 + jose: 6.2.17 + jsdom: 31.0.1 + postal-mime: 4.2.1 + react: 19.3.1 + react-dom: 19.3.1 + react-markdown: 10.1.0 + remark-gfm: 4.0.1 + tailwindcss: 4.3.5 + typescript: 7.0.2 + uqr: 0.1.3 + vite: 8.3.8 + vitest: 5.1.0 + wrangler: 4.162.0 + zod: 4.6.7 + zustand: 5.1.0 diff --git a/scripts/check-static.ts b/scripts/check-static.ts index a4b6abe..7bab009 100644 --- a/scripts/check-static.ts +++ b/scripts/check-static.ts @@ -26,9 +26,15 @@ import { check as secrets } from "./checks/secrets.ts"; import { check as sender } from "./checks/sender.ts"; import { check as vendored } from "./checks/vendored-skills.ts"; import { check as workflows } from "./checks/workflows.ts"; -import { checkPins, readManifest } from "./pins.ts"; +import { checkPins, readAll } from "./pins.ts"; -const pins: Check = { name: "pins", run: () => checkPins(readManifest()) }; +const pins: Check = { + name: "pins", + run() { + const read = readAll(); + return "problems" in read ? read.problems : checkPins(read.workspace, read.packages); + }, +}; const ALL: Check[] = [ pins, copies, diff --git a/scripts/checks/licences.ts b/scripts/checks/licences.ts index a37530f..3bb8a58 100644 --- a/scripts/checks/licences.ts +++ b/scripts/checks/licences.ts @@ -62,13 +62,21 @@ export function checkLicences(listing: Record): string[] { return problems; } +/** + * The licences of every package installed for the workspace at `cwd`, every workspace package's + * dependencies included: without `-r`, `pnpm licenses list` reads the root package's alone (tried + * with a throwaway workspace on 2026-11-19, pnpm 12.10.1; ADR-0018, decision 4). + */ +export function licenceProblems(cwd = "."): string[] { + const json = execFileSync("pnpm", ["licenses", "list", "--json", "-r"], { + cwd, + encoding: "utf8", + maxBuffer: 128 * 1024 * 1024, + }); + return checkLicences(JSON.parse(json) as Record); +} + export const check: Check = { name: "licences", - run() { - const json = execFileSync("pnpm", ["licenses", "list", "--json"], { - encoding: "utf8", - maxBuffer: 128 * 1024 * 1024, - }); - return checkLicences(JSON.parse(json) as Record); - }, + run: () => licenceProblems(), }; diff --git a/scripts/checks/schemas.ts b/scripts/checks/schemas.ts index 6e65133..8f63bf5 100644 --- a/scripts/checks/schemas.ts +++ b/scripts/checks/schemas.ts @@ -2,35 +2,98 @@ * A tool's configuration names the version that is pinned (V1). `biome.json` names its schema * by version; when `@biomejs/biome` is updated and the schema line is not, every run prints a * note that fails nothing. This check fails instead: the version in the schema's address must - * be the exact version `package.json` pins. + * be the exact version the workspace's catalog pins. And a domain of Biome's rules that a catalog + * entry would have turned on is named in biome.json (ADR-0018, step 1). */ +import { readAll } from "../pins.ts"; import { type Check, readJson } from "./lib.ts"; const SCHEMA = /^https:\/\/biomejs\.dev\/schemas\/(\d+\.\d+\.\d+)\/schema\.json$/; -interface Manifest { - devDependencies?: Record; - dependencies?: Record; +/** + * Biome turns a domain of rules on by itself when a dependency is declared with a version at + * least this (biomejs.dev/linter/domains, read 2026-11-19). A dependency named as `catalog:` + * carries no version, so in this workspace no domain turns on by itself: biome.json names every + * one the catalog would have turned on, or its rules stop without a word. + */ +export const DOMAIN_TRIGGERS: Readonly> = { + astro: [["astro", "1.0.0"]], + drizzle: [["drizzle-orm", "0.9.0"]], + next: [["next", "14.0.0"]], + playwright: [["@playwright/test", "1.0.0"]], + qwik: [ + ["@builder.io/qwik", "1.0.0"], + ["@qwik.dev/core", "2.0.0"], + ], + react: [["react", "16.0.0"]], + reactNative: [["react-native", "0.60.0"]], + solid: [["solid", "1.0.0"]], + svelte: [["svelte", "3.0.0"]], + tailwind: [["tailwindcss", "4.0.0"]], + tanstackQuery: [ + ["@tanstack/react-query", "4.0.0"], + ["@tanstack/preact-query", "5.0.0"], + ["@tanstack/solid-query", "4.0.0"], + ["@tanstack/svelte-query", "4.0.0"], + ["@tanstack/vue-query", "4.0.0"], + ], + test: [ + ["jest", "26.0.0"], + ["mocha", "8.0.0"], + ["ava", "2.0.0"], + ["vitest", "1.0.0"], + ], + turborepo: [["turbo", "1.0.0"]], + vue: [["vue", "3.0.0"]], +}; + +const atLeast = (version: string, floor: string) => { + const a = version.split(".").map(Number); + const b = floor.split(".").map(Number); + for (let i = 0; i < 3; i++) { + if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0); + } + return true; +}; + +interface Biome { + $schema?: unknown; + linter?: { domains?: Record }; } -/** What is wrong, given the two files as JSON. */ -export function schemaProblems(biome: { $schema?: unknown }, manifest: Manifest): string[] { - const pinned = - manifest.devDependencies?.["@biomejs/biome"] ?? manifest.dependencies?.["@biomejs/biome"]; - if (pinned === undefined) return ["package.json: @biomejs/biome is not a dependency"]; +/** What is wrong, given biome.json and the catalog of the workspace. */ +export function schemaProblems(biome: Biome, catalog: Readonly>): string[] { + const problems: string[] = []; + const pinned = catalog["@biomejs/biome"]; + if (pinned === undefined) return ["pnpm-workspace.yaml: @biomejs/biome is not in the catalog"]; const schema = typeof biome.$schema === "string" ? SCHEMA.exec(biome.$schema) : null; if (schema === null) { - return ['biome.json: "$schema" is not https://biomejs.dev/schemas//schema.json']; - } - if (schema[1] !== pinned) { - return [ + problems.push('biome.json: "$schema" is not https://biomejs.dev/schemas//schema.json'); + } else if (schema[1] !== pinned) { + problems.push( `biome.json: the schema is ${schema[1]} and @biomejs/biome is pinned at ${pinned}; set "$schema" to ${pinned}`, - ]; + ); + } + const named = biome.linter?.domains ?? {}; + for (const [domain, triggers] of Object.entries(DOMAIN_TRIGGERS)) { + const by = triggers.find(([name, floor]) => { + const version = catalog[name]; + return version !== undefined && atLeast(version, floor); + }); + if (by && !(domain in named)) { + problems.push( + `biome.json: the catalog has ${by[0]}, which turns Biome's "${domain}" rules on; name it under linter.domains, as a catalog entry turns nothing on by itself`, + ); + } } - return []; + return problems; } export const check: Check = { name: "schemas", - run: () => schemaProblems(readJson("biome.json"), readJson("package.json")), + run() { + const read = readAll(); + if ("problems" in read) return read.problems; + return schemaProblems(readJson("biome.json"), read.workspace.catalog); + }, }; diff --git a/scripts/pins.ts b/scripts/pins.ts index a5b3797..b510560 100644 --- a/scripts/pins.ts +++ b/scripts/pins.ts @@ -1,55 +1,82 @@ /** - * Version policy (docs/engineering-rules.md, V1, V3 and V6). + * Version policy (docs/engineering-rules.md, V1, V3 and V6; ADR-0018, decision 4). * - * node scripts/pins.ts --check offline: every dependency is one exact version, and no - * pre-release is used without an entry in `pinExceptions` - * node scripts/pins.ts --resolve [names] network (read-only): for each dependency (or the given - * names) print the newest stable version that is at - * least MIN_AGE_DAYS old - * node scripts/pins.ts --outdated network: list pins that are behind that version; + * node scripts/pins.ts --check offline: every package of the workspace takes its + * versions from the catalog of pnpm-workspace.yaml, and + * the catalog holds one exact stable version for each, + * a 0.x one only with an entry in `pinExceptions` + * node scripts/pins.ts --resolve [names] network (read-only): for each catalog entry (or the + * given names) print the newest stable version that is + * at least MIN_AGE_DAYS old + * node scripts/pins.ts --outdated network: list entries that are behind that version; * exit 1 when one is a major behind without an exception * - * The registry is only read. Nothing is installed and package.json is never written here. + * The registry is only read. Nothing is installed and no file is written here. */ import { readFileSync } from "node:fs"; +import { type Manifest, manifests, readWorkspace, type Workspace } from "./workspace.ts"; export const MIN_AGE_DAYS = 3; const REGISTRY = "https://registry.npmjs.org"; const EXACT = /^\d+\.\d+\.\d+$/; const STABLE = /^\d+\.\d+\.\d+$/; +const FIELDS = [ + "dependencies", + "devDependencies", + "optionalDependencies", + "peerDependencies", +] as const; -interface Manifest { - dependencies?: Record; - devDependencies?: Record; - /** name -> dated reason. A 0.x package or a pre-release needs an entry (V3). */ - pinExceptions?: Record; +/** The workspace at `root` and every package's manifest, or what in it is not read. */ +export function readAll( + root = ".", +): { workspace: Workspace; packages: Map } | { problems: string[] } { + const workspace = readWorkspace(readFileSync(`${root}/pnpm-workspace.yaml`, "utf8")); + if ("problems" in workspace) return workspace; + return { workspace, packages: manifests(workspace, root) }; } -export function readManifest(path = "package.json"): Manifest { - return JSON.parse(readFileSync(path, "utf8")) as Manifest; -} - -export function allPins(m: Manifest): [string, string][] { - return Object.entries({ ...m.dependencies, ...m.devDependencies }); +/** Every catalog entry, as [name, version]. */ +export function allPins(workspace: Workspace): [string, string][] { + return Object.entries(workspace.catalog); } /** V1 and V3, offline. Returns one message per violation. */ -export function checkPins(m: Manifest): string[] { +export function checkPins(workspace: Workspace, packages: ReadonlyMap): string[] { const problems: string[] = []; - const exceptions = m.pinExceptions ?? {}; - for (const [name, version] of allPins(m)) { - if (!EXACT.test(version)) { - problems.push(`${name}: "${version}" is not one exact stable version`); - continue; - } - if (version.startsWith("0.") && !(name in exceptions)) { - problems.push(`${name}: ${version} is a 0.x release and has no pinExceptions entry`); + const names = new Set([...packages.values()].map((one) => one.name).filter(Boolean)); + const used = new Set(); + for (const [dir, manifest] of packages) { + for (const field of FIELDS) { + for (const [name, spec] of Object.entries(manifest[field] ?? {})) { + if (spec.startsWith("workspace:")) { + if (!names.has(name)) + problems.push(`${dir}: "${name}" is not a package of the workspace`); + continue; + } + if (field === "peerDependencies") continue; + if (spec !== "catalog:") { + problems.push( + `${dir}: ${name} is "${spec}"; a version is written once, in the catalog of pnpm-workspace.yaml, and the package says "catalog:"`, + ); + continue; + } + if (!(name in workspace.catalog)) problems.push(`${dir}: ${name} is not in the catalog`); + used.add(name); + } } } - for (const name of Object.keys(exceptions)) { - if (!allPins(m).some(([n]) => n === name)) { - problems.push(`pinExceptions: "${name}" is not a dependency`); + for (const [name, version] of allPins(workspace)) { + if (!EXACT.test(version)) { + problems.push(`catalog: ${name} "${version}" is not one exact stable version`); + } else if (version.startsWith("0.") && !(name in workspace.pinExceptions)) { + problems.push(`catalog: ${name} ${version} is a 0.x release and has no pinExceptions entry`); } + if (!used.has(name)) problems.push(`catalog: ${name} is used by no package`); + } + for (const name of Object.keys(workspace.pinExceptions)) { + if (!(name in workspace.catalog)) + problems.push(`pinExceptions: "${name}" is not in the catalog`); } return problems; } @@ -94,27 +121,36 @@ async function settled(name: string, now: number): Promise { } async function main(argv: string[]): Promise { - const m = readManifest(); + const read = readAll(); + if ("problems" in read) { + for (const p of read.problems) process.stderr.write(`pins: ${p}\n`); + return 1; + } + const { workspace, packages } = read; if (argv.includes("--check")) { - const problems = checkPins(m); + const problems = checkPins(workspace, packages); for (const p of problems) process.stderr.write(`pins: ${p}\n`); - if (problems.length === 0) process.stdout.write(`pins ok (${allPins(m).length} exact)\n`); + if (problems.length === 0) { + process.stdout.write( + `pins ok (${allPins(workspace).length} exact, ${packages.size} package(s))\n`, + ); + } return problems.length === 0 ? 0 : 1; } const now = Date.now(); if (argv.includes("--resolve")) { const names = argv.filter((a) => !a.startsWith("--")); - const list = names.length > 0 ? names : allPins(m).map(([n]) => n); + const list = names.length > 0 ? names : allPins(workspace).map(([n]) => n); for (const name of list) process.stdout.write(`${name} ${await settled(name, now)}\n`); return 0; } if (argv.includes("--outdated")) { let failed = false; - for (const [name, version] of allPins(m)) { + for (const [name, version] of allPins(workspace)) { const latest = await settled(name, now); if (latest === undefined || cmp(latest, version) <= 0) continue; const majorBehind = latest.split(".")[0] !== version.split(".")[0]; - const excused = name in (m.pinExceptions ?? {}); + const excused = name in workspace.pinExceptions; if (majorBehind && !excused) failed = true; process.stdout.write(`${name} ${version} -> ${latest}${majorBehind ? " (major)" : ""}\n`); } diff --git a/scripts/workspace.ts b/scripts/workspace.ts new file mode 100644 index 0000000..2560129 --- /dev/null +++ b/scripts/workspace.ts @@ -0,0 +1,110 @@ +/** + * The workspace as the version rules read it (V1, V3; ADR-0018, decision 4): its packages, the + * catalog that holds every version of the workspace in one place, and the written exceptions, + * which stay in the root `package.json` under `pinExceptions`: a pnpm that the project pins + * refuses a setting it does not know in `pnpm-workspace.yaml` (ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS). + * + * `pnpm-workspace.yaml` is read line by line, not as YAML, and only in the shape this repository + * writes it: top-level keys; under `packages`, list items; under `catalog` and `allowBuilds`, one + * `name: value` per line. A line in another shape is refused, so a version + * cannot hide in a form the rules do not read (a second, named catalog, say). A package is a + * directory listed under `packages` as itself (`.`) or as the directories of one folder + * (`packages/*`). + */ +import { existsSync, readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +export interface Workspace { + /** The directories of the workspace's packages, relative to its root. */ + packages: string[]; + /** Every version of the workspace, by package name. */ + catalog: Record; + /** A 0.x package, or one held back on purpose, with the dated reason. */ + pinExceptions: Record; +} + +export interface Manifest { + name?: string; + /** In the root manifest only: name -> dated reason (V3). */ + pinExceptions?: Record; + dependencies?: Record; + devDependencies?: Record; + optionalDependencies?: Record; + peerDependencies?: Record; +} + +/** Keys whose lines are `name: value`; the others are settings of one line. */ +const MAPS = new Set(["catalog", "allowBuilds"]); +const unquote = (text: string) => text.trim().replace(/^(["'])(.*)\1$/, "$2"); + +/** Reads the workspace file's text, or says what in it is not read. */ +export function readWorkspace(text: string): Workspace | { problems: string[] } { + const workspace: Workspace = { packages: [], catalog: {}, pinExceptions: {} }; + const problems: string[] = []; + let section: string | null = null; + text.split("\n").forEach((raw, index) => { + const at = `pnpm-workspace.yaml:${index + 1}`; + const line = raw.replace(/\s+#.*$/, ""); + if (line.trim() === "" || line.trimStart().startsWith("#")) return; + const top = /^([A-Za-z][A-Za-z0-9]*):(?:\s+(\S.*))?$/.exec(line); + if (top) { + section = top[1] as string; + if (section === "catalogs") + problems.push(`${at}: named catalogs are not read; use the one catalog`); + if (top[2] !== undefined && (section === "packages" || MAPS.has(section))) { + problems.push(`${at}: "${section}" written on one line is not read`); + } + return; + } + if (section === "packages") { + const item = /^ {2}- (\S.*)$/.exec(line); + if (item) workspace.packages.push(unquote(item[1] as string)); + else problems.push(`${at}: not a list item of "packages"`); + return; + } + if (section !== null && MAPS.has(section)) { + const entry = /^ {2}("[^"]+"|'[^']+'|[^\s:'"][^:]*?):\s+(\S.*)$/.exec(line); + if (!entry) { + problems.push(`${at}: not one "name: value" line of "${section}"`); + return; + } + const name = unquote(entry[1] as string); + const value = unquote(entry[2] as string); + if (section === "catalog") workspace.catalog[name] = value; + return; + } + problems.push(`${at}: a line the version rules do not read`); + }); + return problems.length > 0 ? { problems } : workspace; +} + +/** The directories `packages` names, under `root`: `.`, a directory, or `dir/*`. */ +export function packageDirs(workspace: Workspace, root: string): string[] { + const dirs: string[] = []; + for (const pattern of workspace.packages) { + if (pattern.endsWith("/*") && !pattern.slice(0, -2).includes("*")) { + const base = pattern.slice(0, -2); + if (!existsSync(join(root, base))) continue; + for (const name of readdirSync(join(root, base)).sort()) { + if (existsSync(join(root, base, name, "package.json"))) dirs.push(`${base}/${name}`); + } + } else if (!pattern.includes("*")) { + dirs.push(pattern); + } else { + throw new Error(`pnpm-workspace.yaml: the package pattern "${pattern}" is not read`); + } + } + return dirs; +} + +/** Every package's manifest, by its directory. */ +export function manifests(workspace: Workspace, root: string): Map { + const found = new Map(); + for (const dir of packageDirs(workspace, root)) { + const file = join(root, dir, "package.json"); + found.set(dir, JSON.parse(readFileSync(file, "utf8")) as Manifest); + } + // The exceptions are the root manifest's, as pnpm takes no setting of ours beside the catalog. + workspace.pinExceptions = { ...found.get(".")?.pinExceptions }; + return found; +} diff --git a/test/unit/licences-workspace.test.ts b/test/unit/licences-workspace.test.ts new file mode 100644 index 0000000..4ca0fd5 --- /dev/null +++ b/test/unit/licences-workspace.test.ts @@ -0,0 +1,60 @@ +// Copyright 2026 Cloudhal and the Podbay contributors +// Licensed under the Apache 2.0 license found in the LICENSE file. + +/** + * Tier 0: the licence check reads every package of the workspace, not the root's alone + * (`pnpm static licences`; S15, S17; ADR-0018, decision 4). A throwaway workspace is installed + * from local folders, nothing is fetched, and the dependency of its second package declares a + * licence the list refuses. + */ +import { execFileSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { licenceProblems } from "../../scripts/checks/licences.ts"; + +const json = (path: string, value: object) => writeFileSync(path, JSON.stringify(value)); + +describe("the licence check in a workspace of two packages", () => { + const dir = mkdtempSync(join(tmpdir(), "podbay-licences-")); + afterAll(() => rmSync(dir, { recursive: true, force: true })); + + beforeAll(() => { + writeFileSync(join(dir, "pnpm-workspace.yaml"), 'packages:\n - "."\n - "packages/*"\n'); + for (const [name, license] of [ + ["permissive-thing", "MIT"], + ["copyleft-thing", "GPL-3.0-only"], + ] as const) { + mkdirSync(join(dir, "vendor", name), { recursive: true }); + json(join(dir, "vendor", name, "package.json"), { name, version: "1.0.0", license }); + } + json(join(dir, "package.json"), { + name: "root-thing", + version: "1.0.0", + private: true, + dependencies: { "permissive-thing": "file:./vendor/permissive-thing" }, + }); + mkdirSync(join(dir, "packages", "second"), { recursive: true }); + json(join(dir, "packages", "second", "package.json"), { + name: "second", + version: "1.0.0", + private: true, + dependencies: { "copyleft-thing": "file:../../vendor/copyleft-thing" }, + }); + execFileSync("pnpm", ["install", "--offline"], { cwd: dir, stdio: "ignore" }); + }, 60_000); + + it("refuses a licence of the second package's dependency", () => { + expect(licenceProblems(dir)).toEqual([ + 'copyleft-thing: licence "GPL-3.0-only" is not on the allow-list', + ]); + }); + + it("is what pnpm lists only when asked for every package", () => { + const rootOnly = JSON.parse( + execFileSync("pnpm", ["licenses", "list", "--json"], { cwd: dir, encoding: "utf8" }), + ) as Record; + expect(Object.keys(rootOnly)).toEqual(["MIT"]); + }); +}); diff --git a/test/unit/pins.test.ts b/test/unit/pins.test.ts index 5906ca0..3e26325 100644 --- a/test/unit/pins.test.ts +++ b/test/unit/pins.test.ts @@ -1,39 +1,147 @@ -import { describe, expect, it } from "vitest"; -import { allPins, checkPins, newestSettled, readManifest } from "../../scripts/pins.ts"; +// Copyright 2026 Cloudhal and the Podbay contributors +// Licensed under the Apache 2.0 license found in the LICENSE file. + +/** + * Tier 0: every version of the workspace is written once, in the catalog of pnpm-workspace.yaml, + * exactly (V1, V3; ADR-0018, decision 4), and every package of the workspace is held to it, a + * second package as much as the root. + */ +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterAll, describe, expect, it } from "vitest"; +import { allPins, checkPins, newestSettled, readAll } from "../../scripts/pins.ts"; +import { type Manifest, readWorkspace, type Workspace } from "../../scripts/workspace.ts"; const DAY = 86_400_000; +const workspace = ( + catalog: Record, + pinExceptions: Record = {}, +): Workspace => ({ + packages: [".", "packages/*"], + catalog, + pinExceptions, +}); +const packages = (...list: [string, Manifest][]) => new Map(list); +const root: [string, Manifest] = [".", { name: "root", dependencies: { a: "catalog:" } }]; + describe("checkPins", () => { - it("accepts exact stable versions", () => { - expect(checkPins({ dependencies: { a: "1.2.3" }, devDependencies: { b: "10.0.0" } })).toEqual( - [], - ); + it("accepts exact stable versions in the catalog, named as catalog: by every package", () => { + const second: [string, Manifest] = [ + "packages/second", + { name: "second", devDependencies: { b: "catalog:", root: "workspace:*" } }, + ]; + expect(checkPins(workspace({ a: "1.2.3", b: "10.0.0" }), packages(root, second))).toEqual([]); }); - it.each(["^1.2.3", "~1.2.3", "1.x", "latest", "1.2.3-beta.1", "1.2", ">=1.0.0", "workspace:*"])( - "rejects %j", + it.each(["^1.2.3", "~1.2.3", "1.x", "latest", "1.2.3-beta.1", "1.2", ">=1.0.0"])( + "refuses %j in the catalog", (version) => { - expect(checkPins({ dependencies: { a: version } })).toHaveLength(1); + expect(checkPins(workspace({ a: version }), packages(root))).toHaveLength(1); }, ); + it("refuses a second package that writes a version of its own, pinned or not", () => { + for (const spec of ["^2.0.0", "2.0.0", "latest"]) { + const second: [string, Manifest] = [ + "packages/second", + { name: "second", dependencies: { c: spec } }, + ]; + const problems = checkPins(workspace({ a: "1.2.3" }), packages(root, second)); + expect(problems, spec).toEqual([ + `packages/second: c is "${spec}"; a version is written once, in the catalog of pnpm-workspace.yaml, and the package says "catalog:"`, + ]); + } + }); + + it("refuses a package that names a catalog entry that is not there, and an entry nobody uses", () => { + const second: [string, Manifest] = [ + "packages/second", + { name: "second", dependencies: { gone: "catalog:" } }, + ]; + expect(checkPins(workspace({ a: "1.2.3", unused: "1.0.0" }), packages(root, second))).toEqual([ + "packages/second: gone is not in the catalog", + "catalog: unused is used by no package", + ]); + }); + + it("refuses workspace: for a package that is not of the workspace", () => { + const second: [string, Manifest] = [ + "packages/second", + { name: "second", dependencies: { stranger: "workspace:*" } }, + ]; + expect(checkPins(workspace({ a: "1.2.3" }), packages(root, second))).toHaveLength(1); + }); + it("wants a dated exception for a 0.x release", () => { - expect(checkPins({ dependencies: { a: "0.4.0" } })).toHaveLength(1); + expect(checkPins(workspace({ a: "0.4.0" }), packages(root))).toHaveLength(1); expect( - checkPins({ dependencies: { a: "0.4.0" }, pinExceptions: { a: "2026-11-17: no 1.0 yet" } }), + checkPins(workspace({ a: "0.4.0" }, { a: "2026-11-17: no 1.0 yet" }), packages(root)), ).toEqual([]); }); - it("rejects an exception for a package that is not installed", () => { + it("refuses an exception for a package that is not in the catalog", () => { expect( - checkPins({ dependencies: {}, pinExceptions: { gone: "2026-11-17: old" } }), + checkPins(workspace({ a: "1.2.3" }, { gone: "2026-11-17: old" }), packages(root)), ).toHaveLength(1); }); it("passes on this repository", () => { - const manifest = readManifest(); - expect(allPins(manifest).length).toBeGreaterThan(20); - expect(checkPins(manifest)).toEqual([]); + const read = readAll(); + if ("problems" in read) throw new Error(read.problems.join("; ")); + expect(allPins(read.workspace).length).toBeGreaterThan(20); + expect(checkPins(read.workspace, read.packages)).toEqual([]); + }); +}); + +describe("the workspace file", () => { + it("reads packages, the catalog and the other settings of one line", () => { + const read = readWorkspace( + 'packages:\n - "."\n - "packages/*"\n\nminimumReleaseAge: 4320\n# a comment\ncatalog:\n "@scope/a": 1.2.3\n b: 4.5.6 # why\nallowBuilds:\n esbuild: true\n', + ); + expect(read).toEqual({ + packages: [".", "packages/*"], + catalog: { "@scope/a": "1.2.3", b: "4.5.6" }, + pinExceptions: {}, + }); + }); + + it.each([ + ["a named catalog", "catalogs:\n react18:\n react: 18.0.0\n"], + ["a catalog written on one line", "catalog: { a: 1.0.0 }\n"], + ["an entry the reader does not read", "catalog:\n a: 1.0.0\n"], + ["a package that is not a list item", "packages:\n packages/*\n"], + ["an indented line outside the sections", "minimumReleaseAge: 4320\n stray: 1\n"], + ])("refuses %s", (_what, text) => { + expect(readWorkspace(text)).toHaveProperty("problems"); + }); + + describe("on disk", () => { + const dir = mkdtempSync(join(tmpdir(), "podbay-pins-")); + afterAll(() => rmSync(dir, { recursive: true, force: true })); + + it("finds every package of the workspace and refuses the second one's own version", () => { + writeFileSync( + join(dir, "pnpm-workspace.yaml"), + 'packages:\n - "."\n - "packages/*"\ncatalog:\n a: 1.2.3\n', + ); + writeFileSync( + join(dir, "package.json"), + JSON.stringify({ name: "root", dependencies: { a: "catalog:" }, pinExceptions: {} }), + ); + mkdirSync(join(dir, "packages", "second"), { recursive: true }); + writeFileSync( + join(dir, "packages", "second", "package.json"), + JSON.stringify({ name: "second", dependencies: { b: "^1.0.0" } }), + ); + const read = readAll(dir); + if ("problems" in read) throw new Error(read.problems.join("; ")); + expect([...read.packages.keys()]).toEqual([".", "packages/second"]); + expect(checkPins(read.workspace, read.packages)).toEqual([ + 'packages/second: b is "^1.0.0"; a version is written once, in the catalog of pnpm-workspace.yaml, and the package says "catalog:"', + ]); + }); }); }); diff --git a/test/unit/schemas.test.ts b/test/unit/schemas.test.ts index b26468e..ef34c4c 100644 --- a/test/unit/schemas.test.ts +++ b/test/unit/schemas.test.ts @@ -2,15 +2,18 @@ // Licensed under the Apache 2.0 license found in the LICENSE file. /** - * Tier 0: `biome.json` names the schema of the Biome that `package.json` pins - * (`pnpm static schemas`), so an update of the tool cannot leave its configuration behind. + * Tier 0: `biome.json` follows what the workspace's catalog pins (`pnpm static schemas`): it names + * the schema of that Biome, so an update of the tool cannot leave its configuration behind, and it + * names every domain of Biome's rules a catalog entry would turn on, since an entry written as + * `catalog:` turns none on by itself. */ import { readFileSync } from "node:fs"; import { describe, expect, it } from "vitest"; import { schemaProblems } from "../../scripts/checks/schemas.ts"; +import { readAll } from "../../scripts/pins.ts"; const at = (version: string) => ({ $schema: `https://biomejs.dev/schemas/${version}/schema.json` }); -const pinned = (version: string) => ({ devDependencies: { "@biomejs/biome": version } }); +const pinned = (version: string) => ({ "@biomejs/biome": version }); describe("the schema biome.json names", () => { it("is the pinned version", () => { @@ -31,13 +34,33 @@ describe("the schema biome.json names", () => { expect(schemaProblems(biome, pinned("2.6.8"))).toHaveLength(1); }); - it("is refused when the tool is not a dependency", () => { - expect(schemaProblems(at("2.6.8"), { devDependencies: {} })).toHaveLength(1); + it("is refused when the tool is not in the catalog", () => { + expect(schemaProblems(at("2.6.8"), {})).toHaveLength(1); }); it("holds for this repository", () => { - const read = (path: string) => - JSON.parse(readFileSync(new URL(`../../${path}`, import.meta.url), "utf8")) as never; - expect(schemaProblems(read("biome.json"), read("package.json"))).toEqual([]); + const read = readAll(); + if ("problems" in read) throw new Error(read.problems.join("; ")); + const biome = JSON.parse(readFileSync(new URL("../../biome.json", import.meta.url), "utf8")); + expect(schemaProblems(biome, read.workspace.catalog)).toEqual([]); + }); +}); + +describe("the domains of Biome's rules", () => { + const named = (...domains: string[]) => ({ + ...at("2.6.8"), + linter: { domains: Object.fromEntries(domains.map((one) => [one, "recommended"])) }, + }); + + it("are named for every catalog entry that would turn one on", () => { + const catalog = { ...pinned("2.6.8"), react: "19.3.1", vitest: "5.1.0" }; + expect(schemaProblems(named("react", "test"), catalog)).toEqual([]); + expect(schemaProblems(named("react"), catalog)).toEqual([ + 'biome.json: the catalog has vitest, which turns Biome\'s "test" rules on; name it under linter.domains, as a catalog entry turns nothing on by itself', + ]); + }); + + it("are not asked for below the version that turns them on", () => { + expect(schemaProblems(named(), { ...pinned("2.6.8"), react: "15.6.2" })).toEqual([]); }); }); From d7d9e73309377db06adf87f7906cfe28b499e390 Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Thu, 19 Nov 2026 02:32:25 +0300 Subject: [PATCH 2/2] docs: a version is written once, in the workspace's catalog Co-Authored-By: Claude Opus 5.5 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- .claude/skills/podbay-change/SKILL.md | 2 +- .claude/skills/podbay-security/SKILL.md | 4 ++-- AGENTS.md | 2 +- docs/engineering-rules.md | 2 +- docs/status.md | 6 +++--- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.claude/skills/podbay-change/SKILL.md b/.claude/skills/podbay-change/SKILL.md index 3743e98..9b5d7f2 100644 --- a/.claude/skills/podbay-change/SKILL.md +++ b/.claude/skills/podbay-change/SKILL.md @@ -38,7 +38,7 @@ Podbay stores other people's mail. The way of working is part of the product: ev | Edit a file that came from the seed | `node scripts/checks/copies.ts --fix` | | Remove lint warnings or shrink an oversized file | `node scripts/checks/ratchets.ts --update` (it only ever goes down) | | Finish or reorder roadmap work | [`docs/roadmap.md`](../../../docs/roadmap.md) | - | Add a dependency | An exact version at least three days old (`node scripts/pins.ts --resolve `); a 0.x one needs a dated `pinExceptions` entry | + | Add a dependency | An exact version at least three days old (`node scripts/pins.ts --resolve `), written in the catalog of `pnpm-workspace.yaml`, with `catalog:` in the package; a 0.x one needs a dated `pinExceptions` entry in the root `package.json` | 6. **Commit.** Conventional commits, signed off (`git commit -s`). Code with its tests in one commit, documents in another when both are large. Add files by explicit path, then read `git show --stat` of each commit: a commit must contain what its message says. Never push, publish, deploy or open a pull request unless asked. diff --git a/.claude/skills/podbay-security/SKILL.md b/.claude/skills/podbay-security/SKILL.md index 021439c..c9d664a 100644 --- a/.claude/skills/podbay-security/SKILL.md +++ b/.claude/skills/podbay-security/SKILL.md @@ -125,8 +125,8 @@ Each boundary below has the same five lines: what crosses it, the invariant, the - **Crosses:** every package version with its install scripts and licence, every file copied from the seed, and third-party text such as the vendored skill. - **Invariant:** exact pins, at least three days old, installed from a frozen lockfile; build scripts approved one by one. Licences from the allow-list; no AGPL or GPL. No code, schema, test, text, translation or asset from any other mail product, and none named. Every seed file is listed in `copies.json`. The vendored skill is byte-identical to its manifest. -- **Code today:** `scripts/pins.ts`, `scripts/checks/licences.ts`, `names.ts`, `copies.ts`, `vendored-skills.ts`; `minimumReleaseAge` and `allowBuilds` in `pnpm-workspace.yaml`. On every pull request the job `dependency review` (GitHub's action, pinned by commit, read-only) fails on what the pull request adds with a known vulnerability of any severity, or with a licence off the same allow-list. -- **Proof today:** `pnpm static pins`, `licences`, `names`, `copies`, `vendored`; `test/unit/pins.test.ts`, `test/unit/checks.test.ts` (licences, names), `test/unit/vendored-skills.test.ts`; `test/unit/dependency-review.test.ts` (the review's licences and exemptions equal the static check's and the lockfile's); CI installs with `--frozen-lockfile`; `.github/dependabot.yml` opens weekly update pull requests. +- **Code today:** `scripts/pins.ts` and `scripts/workspace.ts` (every package of the workspace, and the catalog of `pnpm-workspace.yaml` where every version is written once), `scripts/checks/licences.ts` (every package, `-r`), `names.ts`, `copies.ts`, `vendored-skills.ts`; `minimumReleaseAge`, which holds for a catalog entry as for any version (tried on 2026-11-19), and `allowBuilds` in `pnpm-workspace.yaml`. On every pull request the job `dependency review` (GitHub's action, pinned by commit, read-only) fails on what the pull request adds with a known vulnerability of any severity, or with a licence off the same allow-list. +- **Proof today:** `pnpm static pins`, `licences`, `names`, `copies`, `vendored`; `test/unit/pins.test.ts` and `test/unit/licences-workspace.test.ts` (a second package of a workspace held to both rules), `test/unit/checks.test.ts` (licences, names), `test/unit/vendored-skills.test.ts`; `test/unit/dependency-review.test.ts` (the review's licences and exemptions equal the static check's and the lockfile's); CI installs with `--frozen-lockfile`; `.github/dependabot.yml` opens weekly update pull requests. - **Open:** a unit test for the `copies` check, the vulnerability audit job (S15), the scheduled job that fails on a pin more than one major behind (V2). ### B10. CI and releases diff --git a/AGENTS.md b/AGENTS.md index 9c6fb3e..e239360 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,7 +63,7 @@ curl -X POST 'http://localhost:5173/cdn-cgi/local/email?from=a@sender.test&to=he Short form; the full text and the reason for each is in [docs/engineering-rules.md](docs/engineering-rules.md). **A rule without an automated check is not a rule**, so the table under it says which checks exist today. -1. **Latest, pinned.** Every dependency is one exact stable version, at least three days old when installed. A 0.x package needs a dated `pinExceptions` entry in `package.json`. (V1, V3, V6) +1. **Latest, pinned.** Every dependency is one exact stable version, at least three days old when installed, written once in the catalog of `pnpm-workspace.yaml`; a package names it as `catalog:`. A 0.x package needs a dated `pinExceptions` entry in the root `package.json`. (V1, V3, V6) 2. **Original work only.** No code, schema, test, text, translation or asset from any other mail product, and no other product named in this repository. No dependency under AGPL or GPL. A file that came from the seed stays listed in `copies.json`; when you change one, run `node scripts/checks/copies.ts --fix`. (S17, S15) 3. **Deny by default.** Every API route is in `workers/auth/route-table.ts` with the right it needs; the guard refuses a route that is not there. Access is decided only by `authorize` in `workers/auth/authorize.ts`. A person who is not a member of a mailbox gets 404, whatever their instance role: managing is not reading. The one exception is who the members are: an owner or administrator of the instance sees and changes them without a membership, with fresh proof and on a record the mailbox's owners read. Accounts are never created over HTTP. (S1, S10) 4. **Mail is hostile bytes.** Route by the envelope recipient, never by a header. A name or id from a message or a request never becomes a storage key without going through `workers/lib/inbound.ts` or `workers/lib/filenames.ts`. (S2, S3) diff --git a/docs/engineering-rules.md b/docs/engineering-rules.md index c0cc73a..e710d03 100644 --- a/docs/engineering-rules.md +++ b/docs/engineering-rules.md @@ -8,7 +8,7 @@ | Rule | Enforcement | |---|---| -| **V1.** Every dependency starts at its latest stable version and is pinned exactly in one place: the package manifest today, a pnpm catalog once the repository has more than one package | The pins check fails on a range or a pre-release | +| **V1.** Every dependency starts at its latest stable version and is pinned exactly in one place: the catalog of `pnpm-workspace.yaml`, which every package of the workspace names as `catalog:` | The pins check reads every package and fails on a range or a pre-release in the catalog and on a version written in a package | | **V2.** Updates arrive as automated weekly pull requests. A new major is adopted within 30 days or gets a dated exception in the catalog. A security fix is merged within 48 hours | Update bot; a scheduled job fails when a pin is more than one major behind without an exception | | **V3.** No pre-release package in production dependencies without a written exception | The pins test rejects `-alpha`, `-beta`, `-rc` and `0.0.x` versions that are not on the exception list | | **V4.** The Workers `compatibility_date` moves forward every month, with the full test run | Scheduled job opens the pull request | diff --git a/docs/status.md b/docs/status.md index ed43245..983662b 100644 --- a/docs/status.md +++ b/docs/status.md @@ -9,13 +9,13 @@ | Check | Rules | Where | |---|---|---| -| Exact pins, 0.x exceptions | V1, V3 | `pnpm static pins`, unit tests | +| Exact pins, 0.x exceptions: every version of the workspace once, in the catalog of `pnpm-workspace.yaml`; every package of the workspace names it as `catalog:` (or `workspace:` for a package of the workspace), and a version written in a package is refused. The exceptions stay in the root `package.json`: a pnpm the project pins refuses a setting of ours in `pnpm-workspace.yaml`. The workspace file is read line by line, and a shape the check does not read (a named catalog) is refused. Biome turns a domain of rules on by itself only for a dependency with a version, so `biome.json` names the domains the catalog would have turned on, and `pnpm static schemas` keeps them in step | V1, V3 | `pnpm static pins`, `pnpm static schemas`; `test/unit/pins.test.ts` (a second package of a fixture workspace that writes its own version is refused), `test/unit/schemas.test.ts` | | Minimum release age | V6 | `pnpm-workspace.yaml` (`minimumReleaseAge`) | | Weekly update pull requests | V2 | `.github/dependabot.yml` | | Compatibility date at most 60 days old | V4 | `pnpm static compat` | | Every Cloudflare surface in the configuration has a sourced ledger entry | V5 | `pnpm static ledger` | | Copied files listed, modified ones marked | S17 | `pnpm static copies` | -| Licence allow-list over every installed package | S15, S17 | `pnpm static licences` | +| Licence allow-list over every installed package, of every package of the workspace (`pnpm licenses list -r`: without `-r` it reads the root's dependencies alone, tried on 2026-11-19 with pnpm 12.10.1) | S15, S17 | `pnpm static licences`; `test/unit/licences-workspace.test.ts` (a throwaway workspace whose second package's dependency is GPL is refused) | | What a pull request adds to the dependencies is read before it merges: it fails on a known vulnerability of any severity in every scope, and on a licence the static check does not allow (the same list, and the same LGPL packages of the toolchain). A licence it cannot detect is reported there and fails only `pnpm static licences`. A required check on `main` since 2026-11-18 | V2, S15, S17 | The job `dependency review` in `.github/workflows/checks.yml` (GitHub's `actions/dependency-review-action`, v5.0.0 pinned by commit); `test/unit/dependency-review.test.ts` holds its inputs to the static check's lists and the lockfile | | No other mail product named | S17 | `pnpm static names` | | No credential shapes, no tracked environment file | S6 | `pnpm static secrets` | @@ -29,7 +29,7 @@ | The guidance is consistent: `AGENTS.md` is one page and names every skill and subagent; skills are named as their folders; a rule's paths still match files; a subagent names only skills that exist and cannot edit; the settings keep local secrets unread and ask before a push or a deploy | D15 | `pnpm static guidance`, `test/unit/guidance.test.ts` | | No lint warning: every rule has one level for every file, no file is exempt, and `pnpm lint` fails on a warning (`--error-on-warnings`), so a clean run prints none. A rule is kept off at a place only by a `biome-ignore` that says why (two keyed lists that are never reordered). File size only goes down | D1, D4 | `pnpm lint`, `pnpm static ratchets` (lint warnings at 0) | | The app's controls are Kumo's (`pnpm static controls`): no `