Skip to content

build: every version lives in the workspace's catalog, and the checks read every package - #96

Merged
Madraka merged 2 commits into
mainfrom
ci/workspace-pins
Nov 18, 2026
Merged

Madraka merged 2 commits into
mainfrom
ci/workspace-pins

Conversation

@Madraka

@Madraka Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

ADR-0018, step 1 of the move: decision 4's first bullet. No file of app/, workers/ or shared/ moves, and no second package is created.

What changes

  • The catalog. The 51 versions move from package.json into catalog: in pnpm-workspace.yaml, and package.json names each as "catalog:".

    • No version changes. Each of the 51 catalog entries in the new lockfile resolves to exactly its own version, and pnpm install resolved 0, reused 556 and downloaded 0. The lockfile diff removes 51 exact specifiers and adds the catalogs: section and 51 'catalog:' specifiers, nothing else.
  • scripts/pins.ts reads the workspace and every package in it, through scripts/workspace.ts. That reader goes line by line, and refuses a shape it does not read, such as a named catalog, catalog: { … }, or an indent it does not know. The rules:

    • a package's dependency is catalog:, or workspace: for a package of the workspace;
    • a version written in a package is refused;
    • a catalog entry is one exact stable version, and a 0.x one needs its dated exception;
    • a catalog entry no package uses, and an exception for something not in the catalog, are refused.

    --resolve and --outdated read the catalog.

  • pinExceptions stays in the root package.json. ADR-0018 says it moves with the versions, but that is not possible. With the project's pnpm pinned (packageManager), pnpm install refuses an unknown setting in pnpm-workspace.yaml with ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS. A throwaway workspace without the pin accepted it silently, which is why I first thought it would work. The reader takes the exceptions from the root manifest.

  • pnpm static licences runs pnpm licenses list --json -r.

  • Something the move would have broken silently, found by the lint ratchet.

    • Biome turns a domain of rules on by itself only when a dependency is declared with a version at least the domain's minimum (biomejs.dev/linter/domains: React is "Enabled when the following dependencies are declared: react: >=16.0.0").
    • Under "catalog:" there is no version, so all six domains that applied on main went quiet: drizzle, playwright, react, tailwind, tanstackQuery and test. It showed only because 19 biome-ignore comments for React's useExhaustiveDependencies became unused.
    • biome.json now names the six under linter.domains. pnpm static schemas reads Biome's version from the catalog, and refuses a catalog entry that would turn a domain on when biome.json does not name it, using Biome's own table of triggers.

The three questions, settled from current sources

  1. Dependabot and a pnpm catalog: yes.

    • Catalog support was rolled out to all users on 2025-02-04 (dependabot-core #10202, closed with "The pnpm catalogs feature has been rolled out and is now available for all users").
    • The defect that kept catalog entries from being updated was fixed on 2025-06-03 (#11953, #12373).
    • GitHub's supported-ecosystems page lists pnpm v7 to v12 for version and security updates, and says nothing about catalogs.
    • Groups and ignore go by dependency name, so ours apply as before.
    • Two issues are open. #14339 (since 2026-03-03): Dependabot's lockfile can drop a catalog package. Since CI installs with --frozen-lockfile, that would be a red pull request, not updates stopping silently. #16766: a catalog split across files with include is not read; we have one file.
  2. pnpm licenses list and workspace packages: only with -r. In a throwaway workspace (pnpm 12.10.1, local folders, nothing fetched), the second package's dependency declared GPL-3.0-only. Without -r the listing had only the root's MIT dependency; with -r it had both. The test below is that workspace.

  3. The three-day rule and a catalog entry: it holds. In a throwaway workspace with minimumReleaseAge: 4320:

    • a catalog entry @cloudflare/workers-types: 5.20261118.1 (published 2026-11-18T01:04Z) was refused with ERR_PNPM_NO_MATURE_MATCHING_VERSION;
    • 5.20261115.1, nearly four days old, installed.

    This was one read of the public registry; nothing was published.

Tests

  • test/unit/pins.test.ts, 23 tests: the catalog's forms; a second package that writes ^2.0.0, 2.0.0 or latest of its own; an entry missing or unused; workspace: for a stranger; 0.x without an exception; the reader's refusals; and a fixture workspace on disk whose second package is found and refused. With the check reading only the root, 5 of them fail.
  • test/unit/licences-workspace.test.ts, 2 tests: the throwaway workspace installed offline from local folders. The check refuses the second package's GPL dependency, and pnpm without -r lists the root's alone. Without -r in the check, the refusal test fails.
  • test/unit/schemas.test.ts, 9 tests: the version read from the catalog, and the domains named or refused.

Locally, pnpm check passed with 22 static checks and 1,007 unit tests. The browser suite was not run locally: no file of the app changed, and CI runs it.

Records

AGENTS.md (rule 1), V1 in the engineering rules, the change skill's table, B9 in the security skill, and docs/status.md (the pins, licences and schemas rows).

🤖 Generated with Claude Code

Madraka and others added 2 commits November 19, 2026 02:32
… 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 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
@Madraka

Madraka commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

audit: pass, once the required checks are green

Read at d7d9e73.

No version changed. I compared the catalog with the pins of package.json on main, entry by entry: 51 and 51, identical. Every dependency in package.json now says catalog:, and the lockfile's changes are the catalog block and the specifiers; no resolution and no integrity line moved.

The checks read every package.

  • pins.ts takes the packages from the workspace file, refuses a version written in a package, a catalog entry that is not one exact stable version, an entry nobody uses, a workspace: that names no package, and an exception for something not in the catalog. The fixture workspace's second package with its own version is refused.
  • The workspace file is read the way the workflow check reads its files: a shape it does not know is refused, so a named catalog or an override block cannot carry a version past it.
  • The licence check asks pnpm for every package. Its test builds a throwaway workspace from local folders with invented packages, installs offline, and shows both things: the second package's licence is refused, and without -r pnpm lists the root's alone.

Two findings of the builder's that the record did not expect, both handled rightly:

  • pinExceptions cannot live in pnpm-workspace.yaml: the pinned pnpm refuses a setting it does not know. It stays in the root package.json. That differs from one clause of ADR-0018's decision 4; the record is not edited, the status row says why, and the project lead is told.
  • Biome turns a group of rules on only for a dependency that has a version, so moving versions to the catalog switched six groups off, and nineteen suppressions went unused. biome.json now names the six, and a check keeps them in step with the catalog. Without the lint ratchet this would have passed as a quieter lint.

Not proven until it happens: that Dependabot updates a catalog entry in this repository, with its groups and its ignore entry. The builder read that it does and that one open defect ends in a red pull request, not in silence. The first update it offers after this merges is read with that in mind; if a week passes with none while updates exist, that is the sign.

Merge with a merge commit, and name the branch's runs.

@Madraka
Madraka merged commit 249c3d7 into main Nov 18, 2026
8 checks passed
@Madraka
Madraka deleted the ci/workspace-pins branch November 18, 2026 23:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant