[RFE] More descriptive error when `spago install` isn't finding package

[Hi-Angel]

This came up as part of a discussion here.

Apparently, packages posted on Pursuit are getting combined into some sort of a "PSC set" which is then used by spago, and then an arbitrary package may or may not be present in such set. When it isn't, spago install prints:

[error] The following packages do not exist in your package set:
[error]   - purescript-halogen-menu, and nor does `halogen-menu`

The specifics that I mentioned above are impossible to infer from this message. A user has to know there exists some sort of versioning. A user can't even guess about such thing existing, because if you go to a Pursuit page of a package, you won't see no "PSC"s mentioned. As result, questions of that kind are getting reiterated by new people.

Proposal

When spago install isn't finding a package, it should print (with X, Y, Z being substituted):

Package X is not present in revision psc-Y you're using. Last known revision that has package was psc-Z. You can add it manually.

Steps to reproduce (in terms of terminal commands)

λ mkdir foo && cd foo
λ spago init
[…]
λ sed -i 's/dependencies = \[/dependencies = \["purescript-halogen-menu",/g' spago.dhall
λ spago install

Expected

Package X is not present in revision psc-Y you're using. Last known revision that has package was psc-Z. You can add it manually.

Actual

[error] The following packages do not exist in your package set:
[error]   - purescript-halogen-menu, and nor does `halogen-menu`

[f-f]

Thanks for the report!

Good error messages are a hard problem! Their author has to lay out enough information to empower the user to tackle the issue at hand, while avoiding being excessively verbose; for this reason a lot of error messages are so dense that they become inscrutable. However, the other side of the spectrum bears the risk of sounding condescending and gets old quick, which may lead to advanced users skimming through the output trying to find some signal in the noise.

In this specific case, the error message assumes that the user knows what a "package set" is. Is this a reasonable assumption? I personally think so - the very first section of the docs, the "super quick tutorial" has a short description of what a spago project contains. In there, there's a link to the relevant section of the docs "what's a package set?

I don't think the proposed error message is an improvement over the current one - a few reasons:

• "package sets" are a broader concept than just the default ones, as you could have custom package sets, local files as package sets, etc. Again, I don't think there's a replacement for reading the docs here
• The psc- naming convention for the versioning of the official sets is outdated - it looks like you're using the legacy Spago (versions 0.21.x), the new naming convention uses semver
• We can do the "last set to include this package was X" for official package sets, but that doesn't work for custom ones, which should be taken into account

I wonder if a few links to the relevant docs session (about what a package set is and how to add custom packages) would be enough to help?

[Hi-Angel]

TL;DR: what about this:

[… here the older message that has always been printed…]
To list available packages use `spago ls packages`

---

In this specific case, the error message assumes that the user knows what a "package set" is. Is this a reasonable assumption? I personally think so - the very first section of the docs, the "super quick tutorial" has a short description of what a spago project contains. In there, there's a link to the relevant section of the docs "what's a package set?

It may be reasonable to assume a user at least vaguely aware of what's a "package set". Though not because they read the links you mentioned (which I, as a new user, never heard of, for example), but rather because PureScript unlikely to be the first programming language, and a user likely ± knows how packaging and versioning works in other langs.

However, it doesn't help with the problem at hand, which is the discrepancy between what a user sees on Pursuit (i.e. that a package isn't bound to specific "package set(s)", as if it's available everywhere) and what actually happens. And the links you referred to mention nothing about that.

So when a message just says "Package X doesn't exist in your package set", the thought "maybe it's a problem with the remote set" will be the last a user would think of. A user more likely to think they mistyped the package name, or maybe gotten into some sort of weird syntax issue… It doesn't help also that Pursuit for some reason writes every package name as purescript-X whereas Spago expects just X (apparently it is so frequent problem that for the case where X is found spago has a dedicated error message asking to drop purescript-).

• The psc- naming convention for the versioning of the official sets is outdated - it looks like you're using the legacy Spago (versions 0.21.x), the new naming convention uses semver

Sorry, I am confused. Yes, indeed I am using 0.21.0 version, however I don't see how could it be legacy when it is literally the latest available release of the PureScript-based Spago rewrite 😅

I don't think the proposed error message is an improvement over the current one - a few reasons:

• "package sets" are a broader concept than just the default ones, as you could have custom package sets, local files as package sets, etc. Again, I don't think there's a replacement for reading the docs here
  […]
• We can do the "last set to include this package was X" for official package sets, but that doesn't work for custom ones, which should be taken into account

Oh, I see. So, at this point I read through your link and now I see the complications. The package X may or may not have been expected to be installed from The Registry, and by providing last known package set revision from The Registry we may be confusing users who expected a different source.

How about this one:

[… here the older message that has always been printed…]
To list available packages use `spago ls packages`

This would remove the hard dependency of the user to the Pursuit site, now a user can manually check what packages are available. This wouldn't help with the question "Why my package set doesn't have this Pursuit package that I clearly see?", but it at least would hint a user to seek the problem on the remote side.

I wonder if a few links to the relevant docs session (about what a package set is and how to add custom packages) would be enough to help?

In this case the specific command spago ls packages might be an excellent hint.

---

Idk how to hint at the discrepancy between Pursuit interface and the actual packages though.

[Hi-Angel]

Btw, I tried creating a commit with the message, but I can't check that it compiles because the current building documentation are obsolete. E.g. running spago bundle -p spago-bin results in suggestion to use bundle-app. But then even when it's used spago simply prints help message, without any errors. I tried skipping that step and just running spago build, but I guess it doesn't work like that because it's not finding spago.dhall file.

[Hi-Angel]

Anyway, I used lsp server to check that there isn't syntax errors, and CI has build checks as well, so I sent a PR.