* docs: lint prose with Vale
Add Vale with an in-repo style, .vale/styles/pnpm, that turns the
writing rules in AGENTS.md and the Google developer documentation style
guide into lint rules. The stock Vale packages (Google, Microsoft,
RedHat, write-good) were too noisy to block on, for example 1,300
passive-voice hits in the v12 docs alone, so the rules are written for
this repo, following the GitLab model. Each one links the guideline it
enforces.
Levels:
- error, fails CI: dashes, plain-word substitutions, condescending
words, "please", "note that", hedges, puffery, optional plurals,
exclamation marks, ellipses, curly quotes, generic link text, product
spellings, sentence-case headings, repeated words, double spaces,
implementation history in comments; in changesets, bold or italic
emphasis, internal names and release-line names.
- warning: future tense, sentences over 30 words, "instead of" and
"so that" tails in changesets.
- suggestion: passive voice.
.vale.ini scopes the rules. Docs get every rule. Contributor Markdown
and code comments keep dashes and headings as warnings until their
roughly 8,100 em dashes are rewritten. Released changesets stay in
.changeset/ and are not rewritten, so lint-prose.mjs lints only the
changesets added since PROSE_BASE (the PR base in CI).
The prose workflow installs a pinned, checksum-verified Vale release and
runs `pnpm lint:prose`. The rest of this change rewrites the existing
docs, READMEs, contributor Markdown, and code comments to pass the
error-level rules. Only prose and comment text changed. Renamed
headings keep their anchors.
Spelling stays with cspell, which checks identifiers that Vale does not
see.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: keep prose lint from flattening meaning
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
`pnpm self-update` located the pnpm pin on its own: it read only
`package.json` in `--dir`. Run inside a workspace package, it missed the
pin in the workspace root's manifest, left the pin alone, and switched the
global pnpm instead. Under Corepack or Homebrew it refused outright. A pin
in `package.yaml` or `package.json5` was missed the same way.
`PinRoots`, the pre-command pass's pin locator, moves to `package_manager`
and becomes the one place both read from. The manifest at the workspace
root (or `--dir` outside a workspace) holds the pin, in whichever basename
it uses, and the env lockfile directory follows `lockfileDir`.
self-update now writes the manifest it read back in its own format and
records `packageManagerDependencies` where the pre-command pass reads them.
The Corepack/Homebrew refusal for a project without a pin now runs after
config loads, so it reads the pin through the same locator. The wasm
refusal still runs before.
pnpm v11 already reads the pin from the workspace root, so this is a
v12-only fix.
Part of https://github.com/pnpm/tasks/issues/144
`pnpm self-update` refused to run when Homebrew installed pnpm or
Corepack ran it, even in a project that pins pnpm. The refusal guards the
global switch, which would install a second pnpm shadowed by the one on
PATH. Writing the pin touches nothing Homebrew or Corepack manages.
Both CLIs now skip only the global switch under an external manager and
report it after the pin update. Without a pnpm pin the command still fails
with ERR_PNPM_CANT_SELF_UPDATE_IN_HOMEBREW / _IN_COREPACK.
In pnpm v12 the check stays in the dispatcher before config is loaded. It
now reads package.json from the same directory as the handler to decide
whether a pin exists.
Closespnpm/pnpm#17001
Code blocks that hold only shell commands now use the `sh` language,
and blocks showing a file's contents carry a `title` naming the file,
across the pnpm v12, pnpm v11, and pnpr docs. Bold file-name labels
above code blocks are folded into the titles.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
`pnpm self-update` installs the target pnpm into the global packages
directory and links it into PNPM_HOME. It never touches the Homebrew
keg, so a Homebrew user ended up with a second pnpm that the Homebrew
binary on PATH kept shadowing. The update reported success while
`pnpm -v` stayed the same, and later runs declined because the target
was "already installed globally".
Both CLIs now detect a running pnpm that lives inside a Homebrew keg
(`<cellar>/pnpm/<version>/` or `<cellar>/pnpm@<major>/<version>/`) from
its canonical path and fail with ERR_PNPM_CANT_SELF_UPDATE_IN_HOMEBREW,
pointing at `brew upgrade <formula>`. The check sits next to the
existing Corepack refusal, before project config is loaded.
Closes https://github.com/pnpm/pnpm/issues/16547
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
