TODO:

- [ ] Decide on the proper name of the "element" configuration option
- [ ] Check if this works in various corner cases
- [ ] Add tests
- [ ] Add docs

Cyclic imports can be confusing because the order in which we import
dependencies can make the import fail or not. We should not rely on
ordering of imports for our code. This fixes everywhere possible the
imports and silence explicitely some which are not convenient or would
require big refactors

Replace YAML internals with a new Node type, and refactor everything
to use it cleanly.

This work was also by James Ennis <james.ennis@codethink.co.uk>

Signed-off-by: Daniel Silverstone <daniel.silverstone@codethink.co.uk>

The new YAML world order doesn't need the YAML cache, so remove it
before we begin the change.

Signed-off-by: Daniel Silverstone <daniel.silverstone@codethink.co.uk>

Give better error messages to the user by including provenance. Pass
'provenance' through to places where we raise exceptions in _get_loader.

For example, here you can see the provenance information now included
(the bit before the ':'):

    callHello.bst [line 8 column 4]: Could not find the project.conf
    file in the project referred to by junction element
    'hello-junction.bst'.

If we're creating a project for a junction, then don't go looking for
the project directory - the path has already been given to us.

This means that we can now detect when junctions are missing a
'project.conf', and importantly we don't accidentally start resolving
elements in the enclosing project.

Add tests to cover workspaced, local, and git repo cases. Note that
this is also the first test coverage for the INVALID_JUNCTION path.

In later work we might extract the _find_project_dir magic out of the
Project class, so that there are no surprises when instantiating it.

I found the original message confusing - it would talk about wanting a
project at '.', without a frame of reference. After re-reading the code
and junction docs it made more sense, I think this version would save
folks the trouble.

Removing all mention of it, if it's not specified. If it is specified
then explain it a bit more, i.e.

Before:

    Could not find the project.conf file for junction element at
    hello-junction.bst [line 1 column 0]. Expecting a project at path
    'project'

After:

    Could not find the project.conf file in project referred to by
    junction element 'hello-junction.bst'. Was expecting it at path
    'project' in the junction's source.

If no 'path' specified in the junction:

    Could not find the project.conf file in project referred to by
    junction element 'hello-junction.bst'.

This involve introducing new Consistency states `STAGED` and `BOTH` that
represent when the source is just in the local CAS and in both the local
CAS and unstaged in the source directory.

Sources are staged for each element into the local CAS during the fetch
stage. If the sources are in the local consistency state `STAGED` when
wanting to open a workspace, the original sources are fetched.

Relavant tests this affects have been changed.

Part of #440

When a file is missing in a subproject, it is not particularly meaningful
to specify the filesystem path to the elements directory of the subproject,
as this temporary staging directory belongs to BuildStream and not the user.

Instead, when a file is missing in a subproject, specifying the junction name
is more useful.

This fixes an aspect of #947