Package documentation should detail trust boundary

[SeanTAllen]

Currently the package documentation doesn't discuss how search path resolution is done, nor what that means for a "trust boundary".

Currently ponyc searches for package use "foo" by the following:

• checks if "foo" is an absolute path on disk. if yes, the package at that absolute path

• checks for "foo" against base

  "base" here is relative the compilation directory. i.e. where our actor Main is or otherwise the directory/package that we are compiling. So for example, if there is a directory "foo" in base, then we will resolve "foo" to base/foo.

• checks the search paths for "foo"

  paths are controllable via the PONYPATH environment variable (this is how corral manages deps) or via the --path ponyc option.

---

It is important to understand the ramifications of search from "base".

• Anything that you reference via a relative use like "use ../foo" is resolved via base. We do not check search paths for relative package references.
• Anything you do via "use foo" might be resolved via base. This means from base if you have the following layout:

base/
  main.pony
  assert/
    assert.pony

You have overriden the standard library "assert" package with your own. You can replace the entire standard library this way if you wanted. Odds are folks don't want to do that, but they can.

The important thing here is that everything you put relative to your base is effectively "part of your application" or "part of your library" and it is "trusted" like your other code. Installing 3rd party code relative to base and referencing it as such makes it indistinguishable from your own code to the library. This has interesting ramifications for allowing or denying FFI usage to packages in addition to overriding parts of the standard library that a power user might want to do.

Detailing base resolution means in terms of a "trust boundary" is important and needs to be detailed along with the package resolution rules.