mirror of
https://github.com/pnpm/pnpm.git
synced 2026-11-02 03:59:07 -05:00
docs-migration-runtime-setting
13
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Zoltan KochanandClaude Opus 5.5
|
6f95957063 |
docs: lint prose with Vale (#17238)
* 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> |
||
|
KhảiandClaude Opus 5
|
1606ba03fb |
docs: add the documentation and comment principles and apply them (#16516)
* docs(agents): add the documentation and comment principles Import the principles that transfer from KSXGitHub/perfectionist's contributor guide, plus four of our own: concise and non-repeating text, structured text over prose, removal over addition when reviewing or fixing nitpicks, and a definition of the user-facing text that must not name implementation details. The root guide's "Comments" section gains "Register", "Prose that cannot go stale", "User-facing text", and "Reviewing documentation and comments". The pacquet style guide adds the Rust specifics (clap and napi doc comments are user-facing; a default is documented on the field, not the variant). DOCUMENTATION.md gains the renderer and link table for each markdown surface. The guides themselves are brought in line: counts over growable lists become plain references, a quoted heading becomes an anchor link, and the size limits are stated once, in the style guide, instead of three times. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs: keep user-facing text free of implementation names The `@pnpm/napi` README and type declarations named the Rust engine, the in-repo package name, and TypeScript internals (`filterPkgsDiff`, `nameFormatter`) that a user of the addon cannot reach. The pnpmfile page in both docs trees explained a limitation by the IPC mechanism behind it. Four changesets named the release line or implementation, which the package targets already express. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating and stale comments in pack, modules-yaml and nine more crates Apply the comment principles to pack, versioning, pnpr-client, package-is-installable, fs-packlist, workspace-task-scheduler, engine-runtime-node-resolver, exportable-manifest, modules-yaml, pnpr-registry, and pnpr-auth. Removed: call-site comments that repeat the callee's doc, module rosters of exports that the `pub use` lines already list, "not yet implemented" notes for behaviour that exists (`beforePacking`, `hoistedLocations`), body narration, and history framing. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating and stale comments in the small resolver, catalog and pnpr crates Apply the comment principles to the local, tarball, default, deno and jsr resolvers, the catalog crates, detect-libc, config-parse-overrides, env-replace, git-utils, matcher, diagnostics, and the pnpr policy, cargo, error, osv and fixture crates. Removed: parentheticals that repeat a `#[diagnostic(code)]` attribute, counts over lists of variants, callers and entry points, rosters of callers, doc paragraphs that repeat a sibling's or the module's text, comments narrating the match arms or condition below them, and history framing. The `pnpr-prepare --help` text no longer names the test harness. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating and stale comments in publish, workspace, registry and graph-hasher Apply the comment principles to publish, auth-commands, registry, workspace, lockfile-verification, default-reporter, the git resolver, deps-inspection, hooks, graph-hasher, package-manifest, and the pnpr shared-artifacts and route crates. Removed: a module roster of every export, counts over lists, plan notes for work that landed ("Phase 5", "Phase 6"), call-site comments repeating the callee's doc, docs narrating match arms, a default claim on a `#[default]` variant, a misattached doc, and history framing. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating comments in napi, reporter and pnpr crates Apply the comment principles to napi, reporter, resolving-resolver-base, real-hoist, git-fetcher, workspace-manifest-writer, and the pnpr config and storage crates. Removed: "Mirrors X in index.d.ts" sentences on `#[napi]` items and other implementation names in addon-facing docs, stale "not emitted yet" and "when it lands" notes for behaviour that exists, step-by-step comments narrating the body, emit-site and caller rosters, docs duplicated from a sibling or the module, a doc attached to the wrong item, and history framing. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs: cut restating and stale comments across the remaining crates and pnpm11 Apply the comment principles to the rest of the Rust workspace and to the TypeScript CLI: the cli crate and its clap definitions, package-manager, config, patching, the deps resolver, lockfile, pnpr, the npm resolver, tarball, network, executor, cmd-shim, the benchmark and fixture tooling, and the pnpm11 packages. Removed: comments narrating the body, docs repeating a callee's, a sibling's or the module's text, counts over growable lists, rosters of callers and exports, "not yet implemented" notes for behaviour that exists, history framing, and `@param` lines restating a signature. One exception to comment-only: in `pnpr/crates/pnpr/src/resolver/resolve.rs` the `Workspace` struct sat inside the doc block written for `resolve`, so the struct moved above it and each doc now attaches to its own item. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut body narration and duplicated docs in resolver, fs and package-manager Removed: a numbered "Sequence:" list narrating `ensure_file`'s body and the paragraph restating its backoff constants, the stress-test module doc's roster of its own tests, refactor-history paragraphs in the peer walk's finalize pass, call-site and caller-side copies of a callee's doc (the `optional` AND-fold stays documented on `register_seeded_package` and on `ResolvedPackage`), a verbatim quotation of a TypeScript test's expected output in the pnpr search module doc, and field and digest-input rosters in the package-manager. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(deps-restorer): cut plan references and re-attach misplaced docs Removed the "slice 4" plan references and the comments narrating the bodies they sat above. The `Auto` downgrade-chain doc moved from `copy_and_log` to `auto_link`, the function it describes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(deps-restorer): cut the remaining body narration in the hoist path Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs: cut the last body narration and a history clause in the cmd-shim test `build_graph.rs` kept a `patches` parameter doc that re-derived what `BuildOptions::patches` documents. The PowerShell-arguments test on main said the arguments survived "before the shim ended its batch context too", which describes the change rather than the behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cmd-shim): point the PowerShell-shim link at its current module Main moved `wants_powershell_shim` into `windows_shim_policy`, so the shim writer's link to it no longer resolved and `cargo doc` failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cli): link the fixture the ignored-build setup installs The shortened doc named `workspace_with_unapproved_build` in backticks, which `perfectionist::bare_identifier_reference` rejects for an item that resolves in scope. It is an intra-doc link now. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): restore two contracts and fix four dangling references A review of this branch's sweep flagged seven places. Six needed a change: - `from_ini` documents again that a relative `cafile=` resolves against `npmrc_dir`, a precondition its callers have to honour. - `hash_object` documents again that the private serializer's bytestream has to match pnpm 11's, because the digest is persisted and read by both. - The hooked-manifests note no longer says "above" of a gate that lives in another module. - The store-dir race test states its synchronization contract instead of labelling it "Post-Option-C". - `GraphNodeHashOptions.nodeVersion` keeps `undefined` as a literal. - The pnpr streaming module drops the sentence fragment that introduced its list. The seventh, a `beforePacking` limitation in exportable-manifest, stays removed: the note said the pnpmfile bridge cannot supply that hook, and `pnpm_pack::lifecycle::apply_before_packing` has been running it since before this branch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cli): say in `pnpm why --help` that `--exclude-peers` is ignored Demoting the caveat to an ordinary comment took it out of the help, which then advertised a flag that does nothing: `WhyArgs::run` never reads `exclude_peers`, and pnpm 11's `why` handler never forwards its `excludePeers` either. The doc comment states that behavior in the words a user sees, and the parity reason stays in a comment beside it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cli): drop the doc comment that described the wrong module The comment described the `pnpm_deps_inspection as deps_tree` re-export above it, but a doc comment attaches to the item that follows, so rustdoc showed it as the description of `mod dispatch`. The `use` item already names the alias, so the comment goes rather than moving. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Zoltan Kochan
|
4edeef9176 |
style(ts): port the perfectionist lint rules to ESLint (#16415)
Add TypeScript ports of the perfectionist rules that the Rust workspace enforces through dylint.toml to @pnpm/eslint-config, with the same limits, and fix every finding that needs no refactor. The size and shape rules (function length, cognitive complexity, nesting, local bindings, file length) are enforced for packages that already meet them. The packages that do not are listed in PENDING_SIZE_AND_SHAPE_REFACTOR in eslint.config.mjs and are refactored in follow-up changes. The custom rules mirror perfectionist's semantics rather than reusing sonarjs or max-lines-per-function, so that one limit means the same thing in both codebases: a closure is a level of the body that contains it, a nested function declaration is measured on its own, and a test-framework callback plays the role of a #[test] function. Bugs found and fixed along the way: - a registry error body cut at exactly 64 KiB lost its truncation marker - removing a dependency could leave dangling .bin shims - constructor/__proto__ names crashed the projects graph, were skipped by the injected-deps syncer, and were dropped from writeWantedLockfile's returned lockfile The CI chunk runner learns to run the node:test suite of the ESLint config package. |
||
|
|
37227c0480 |
fix: explain SSH publickey failures when installing git dependencies (#15877)
Fetching a git dependency locked to an SSH remote now says to load a key with ssh-add when git reports a publickey refusal, and still explains how to re-record a pre-v11.21 entry with pnpm update. Resolving an SSH URL that fails the same way shows that advice plus a local HTTPS insteadOf rewrite when the remote logs in as git. The rewrite uses a shell-safe host and no userinfo, so a password or a hostile host cannot reach the command. Closes pnpm/pnpm#13743 --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Zoltan Kochan <z@kochan.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
Zoltan Kochan
|
5b1431c199 |
fix(git): run ssh in batch mode so a hidden passphrase prompt cannot hang the install (#15196)
The default reporter repaints the terminal over anything git or ssh prints, so when a git dependency's SSH remote needs a key passphrase or a host key confirmation the prompt is invisible and `pnpm install` looks hung. `GIT_TERMINAL_PROMPT=0` already made git's own credential prompts fail fast; ssh prompts on the terminal directly, so it needs `BatchMode=yes` through `GIT_SSH_COMMAND` to fail the same way. Both the git resolver's `ls-remote` and every git invocation of the git fetcher now go through one helper, `nonInteractiveGitEnv` in `@pnpm/network.git-utils` and `disable_git_prompts` in `pnpm-git-utils`, that sets both variables. The ssh override is skipped when the user already selected the ssh command through `GIT_SSH_COMMAND`, `GIT_SSH`, or the `core.sshCommand` git setting, so a custom key or a plink setup keeps working, and setting `GIT_SSH_COMMAND=ssh` opts back into prompting. Closes pnpm/pnpm#2227 |
||
|
Minha KangandZoltan Kochan
|
cc5df67f2f |
fix(git-resolver): keep the committish in the recorded git specifier (#14007)
A hosted git specifier that resolved over HTTPS without the repository being provably public lost its committish from the specifier written back to the manifest: `pnpm add owner/repo#develop` recorded `git+https://github.com/owner/repo.git`. The URL that branch records doubles as the `git ls-remote` target, which must carry no committish, so it was built with `noCommittish`. The committish still reached resolveRef, so the install pinned the right commit and nothing looked wrong — until the next re-resolve read a specifier that no longer named a branch and moved the dependency to the default branch. Keep the `ls-remote` target committish-free and build the recorded specifier from the same host template with the committish left in, which is what every other branch of fromHostedGit already produced through shortcut(). pacquet reaches its equivalent branch only for a URL carrying its own credentials, and drops the committish there the same way; it is fixed alongside. Fixes pnpm/pnpm#13999 --------- Co-authored-by: Zoltan Kochan <z@kochan.io> |
||
|
Luan TaraschiandZoltan Kochan
|
5610fefa38 |
fix(git-resolver): resolve ssh git URLs that carry no user info (#13726)
## Summary
SSH Git dependencies without user information could crash during parsing because the TypeScript resolver expected every authority to contain `user@host`. Bracketed IPv6 addresses exposed a second issue: colons inside the address were mistaken for an SCP-style separator.
This change keeps the TypeScript and Rust implementations aligned:
- the host lookup falls back to the full authority when no user information is present;
- only the part after a bracketed host is inspected for an SCP separator or port;
- the Rust rewrite finds the final separator directly with `rfind(':')`, which expresses the intended operation without allocating a temporary vector;
- regression coverage includes no-user-info URLs, bracketed IPv6 hosts, ports, SCP-style paths, and path extraction.
---------
Co-authored-by: Zoltan Kochan <z@kochan.io>
|
||
|
Zoltan Kochan
|
cd73c55950 |
fix(git-resolver): say which git dependency could not be reached, and how (#13794)
A specifier that does not ask for SSH resolves over HTTPS, because the URL pnpm records is shared by every machine that installs the lockfile (pnpm/pnpm#13290). On a machine whose git cannot use that transport - a container without the host's CA certificates, say - resolution then failed with a raw execa dump: "Command failed with exit code 128: git ls-remote -- 'https://github.com/...'" and a JS stack, naming neither the dependency nor a way forward. A failed ls-remote is now ERR_PNPM_GIT_RESOLVE_FAILED, naming the dependency and redacting the credentials a URL git echoes back can carry. When the resolution went over HTTPS, the error also says why, and points at git's own url.<base>.insteadOf to substitute the transport on this machine only, leaving the recorded URL alone. A missing git binary says so instead of surfacing a bare spawn error. The TypeScript resolver also stops probing anonymous HTTPS git access for a repository the visibility probe already proved public: both outcomes of that probe recorded the same resolution, so its only effect was an extra ls-remote round-trip per git dependency. pacquet never probed. Carrying the code and the remediation across pacquet's type-erased resolver seam takes the mechanism resolver-base documents for exactly that: the diagnostic is boxed outermost and recovered by downcast, in the tree walker and in add. Related to pnpm/pnpm#13743. |
||
|
Minha KangandZoltan Kochan
|
de1c7be5fa |
fix(git-resolver): make the ls-remote prompt guard reach git (#13523)
#13471 passed GIT_TERMINAL_PROMPT=0 in the options given to graceful-git, but graceful-git forwards only `cwd` to the process it spawns, so the override never reached git: a repository that needs credentials still made git prompt on the terminal, and `pnpm outdated` with a private GitHub Actions repo (as well as resolving a private git dependency) still hung. Spawn git through safe-execa directly with the guard in the child environment, keeping the single-retry policy of the ref-read call site. The regression went unnoticed because the test mocked graceful-git and asserted that the env option was handed to it, not that it reached git; the mocks now sit on the process-spawn boundary and every invocation is checked, so dropping the guard fails 25 tests. The Rust runner sets the variable on the Command itself and was already correct. Fixes pnpm/pnpm#13522 --------- Co-authored-by: Zoltan Kochan <z@kochan.io> |
||
|
|
8ae2e281ff |
fix(git-resolver): fall back to HTTPS instead of SSH for shorthand git specs on CI (#13290)
Two flaws let a transient probe failure record an SSH URL for a spec that never asked for SSH: the visibility HEAD probe ran once with retries disabled and treated any failure as private, and the SSH ls-remote probe ran before the anonymous HTTPS one. On a machine with SSH keys, a throttled HEAD request resolved a public repo to git@host:..., breaking later installs on keyless CI runners with Permission denied (publickey). The resolver now retries transient HEAD failures, probes anonymous HTTPS git access before SSH for every representation except explicit SSH URLs, falls back to HTTPS when every probe fails, and records the host-archive tarball only for repos proven public - otherwise the resolution stays type: git so ambient credentials apply. TypeScript CLI only: pacquet resolves this bug class structurally via the v12 identity redesign (pnpm/pnpm#13684), which supersedes the Rust-side commits this PR previously carried. Closes pnpm/pnpm#13276. Co-authored-by: Zoltan Kochan <z@kochan.io> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
Alessio AttilioandZoltan Kochan
|
b287582858 |
fix(git-resolver): pass GIT_TERMINAL_PROMPT=0 to prevent interactive prompts in git ls-remote (#13471)
The git ls-remote command spawned by the GitHub Actions checker now includes GIT_TERMINAL_PROMPT=0 in its environment. This ensures that the command fails immediately instead of blocking the user on an interactive prompt when the repository is private and the user lacks HTTPS credentials. Closes pnpm/pnpm#13421 --------- Co-authored-by: Zoltan Kochan <z@kochan.io> |
||
|
Zoltan KochanandClaude Fable 5
|
d2ed60afba |
test: make git-resolver and dlx git tests immune to GitHub flakiness (#12885)
The git-resolver unit tests hit live github.com by default: the mocks for fetchWithDispatcher and graceful-git existed, but beforeEach restored the real implementations. When GitHub throttles the shared CI runner IPs, the HEAD probe in isRepoPublic() fails (it has zero retries and treats any error as "private"), and resolution silently degrades from the hosted tarball to a git clone, changing the resolved id and failing the assertions. This broke the main branch build at https://github.com/pnpm/pnpm/actions/runs/29026897310/job/86153736091 The mocks are now the default: fetch reports every repository as public and graceful-git serves ls-remote output from a fixture table captured from the real repositories, with the same commit hashes the assertions already expected. The private-repo-over-HTTPS test now calls mockFetchAsPrivate() explicitly instead of relying on a real 404 for the nonexistent github.com/foo/bar. The one live-network case in parsePref.test.ts got the same treatment. The suite drops from ~40s to under half a second and runs offline. The dlx e2e test stays a genuine end-to-end test against GitHub, but its allowBuild list now approves both resolution shapes of the same commit (codeload tarball and git+https clone), so the resolver's rate-limit-induced fallback no longer trips the GIT_DEP_PREPARE_NOT_ALLOWED gate, as seen in https://github.com/pnpm/pnpm/actions/runs/29029971938/job/86170695840 Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|
Zoltan Kochan
|
fc2f33912e |
refactor: move the TypeScript pnpm CLI into a pnpm11/ directory (#12537)
The TypeScript pnpm CLI freezes at v11; pnpm 12 will be the Rust pacquet port. To make that split legible, all TypeScript source, test, and build directories move under a new top-level pnpm11/ directory. The name states the version boundary rather than implying a behavioral fork, since the two stacks are meant to behave identically. Scope is source-only: the shared workspace root stays at the repo root. pnpm-workspace.yaml, package.json, pnpm-lock.yaml, .pnpmfile.cjs, .meta-updater, __patches__, .changeset, .husky, and the lint/spell configs remain in place, so one pnpm workspace and one Cargo workspace still span all three products. pnpr/client and pacquet/tasks/registry-mock stay as cross-product workspace members. Rewiring the move required: - pnpm-workspace.yaml globs prefixed with pnpm11/ - root package.json script paths, eslint.config.mjs, tsconfig.lint.json, .gitignore, and CODEOWNERS updated - .meta-updater/src/index.ts literals repointed (pnpm11/pnpm/package.json, pnpm11/__utils__, pnpm11/__typings__, and the main package directory) - regenerated every moved package's repository/homepage URL via meta-updater - pnpm11/pnpm/bundle-deps.ts and __utils__/scripts/src/typecheck-only.ts climb one more level to reach the repo root .meta-updater stays at the repo root because @pnpm/meta-updater resolves its config at <cwd>/.meta-updater/main.mjs. TS CI (.github/workflows/ci.yml) now only runs when pnpm11/-relevant paths change, via a dorny/paths-filter changes job plus a TS CI / Success aggregate gate; branch protection should require only that gate. |