docs(site): better explain name~version semantics

[yyxi]

Question

Hi Jamie, thanks for syncpack, and congratulations on the v14 release and the Rust rewrite. I got confused by name~version when I tried to model devEngines.runtime and devEngines.packageManager, and I want to check that I understood the intended behavior correctly.

I first configured "path": "devEngines.runtime" and "namePath": "name" because the docs say name~version stores the name and version in different locations and illustrate that with a top-level { "name": ..., "version": ... } object. I read that as meaning path could point to the containing object and namePath could be relative to it. syncpack only matched after I changed both entries to package-root paths that point directly to strings, for example devEngines.runtime.version and devEngines.runtime.name. Is that the intended behavior for name~version?

If so, would you be open to documenting two points explicitly: for name~version, both path and namePath must point directly to string fields from the package root, and namePath is required for that strategy. The implementation appears to require it, but the docs only include it in the local example and do not mark it as required in prose. A short devEngines example would likely prevent the same mistake, especially with pnpm 11 moving more configuration toward devEngines.packageManager and devEngines.runtime

Code of Conduct

• I agree to follow the Code of Conduct

[JamieMason]

Hey @yyxi, that's right.

namePath

A child.grandChild.greatGrandChild.etc path from the root of the package.json object to a string value containing only the name of the dependency – like how the name property is for a package you develop.

path

A child.grandChild.greatGrandChild.etc path from the root of the package.json object to a string value containing only the version specifier of the dependency – like how the version property is for a package you develop.

So

• Both are absolute paths from the root.
• Both need to point to the string value rather than an object parent of it.

And I think that's everything. Let me know if this is still confusing or anything else is missing.

[yyxi]

Thank you @JamieMason, that clears it up!

[JamieMason]

Reopening to track updating the docs.