feat: relative directory usage type

[andrius-puksta-sensmetry]

This PR introduces support for referencing local directory paths as project dependencies, alongside the existing IRI/URL-based usages. It also refines the resolution API to carry richer context and adds an experimental CLI subcommand to expose the new capability.

New Directory usage type

A new variant Directory { dir, publisher, name } is added to InterchangeProjectUsageG. It serialises as {"dir": "relative/path", "publisher": "...", "name": "..."}. It only supports local_src projects. KPARs will use another type. This is to keep resolution unambiguous. It allows avoiding resolution altogether for typed usages, although currently resolution is still done.

ResolutionInfo replaces IRIs

ResolveRead now takes a ResolutionInfo instead of an IRI. ResolutionInfo wraps InterchangeProjectUsage and an optional base_path for resolving relative filesystem paths. A custom Hash implementation is included so that pubgrub identifies packages by identity (publisher + name) rather than version constraint, preventing the same package from appearing multiple times in the solution when it has different constraints/path in different dependents.

experimental CLI subcommand (sysand/src/cli.rs)

Adds sysand experimental add --dir <path> and sysand experimental remove <publisher> <name>:

• add computes a path relative to the current project, populates publisher/name from the dependency's .project.json, and creates a Directory usage.
  Currently no source overrides are supported by this command. It does not seem useful to support this at add time, considering that typed usages will support everything supported by source overrides, so these usages can be added directly instead of going through overrides.
• remove removes a project by its publisher and name. This will work for all usage types that include a publisher and name, currently I plan for all typed usages to have this for consistency.

Commands are separate from regular add/remove to avoid breaking changes; also it's not clear how the UX will work for other usage types (add especially), so this leaves room to experiment.

[vytautas-astrauskas-sensmetry]

It serialises as {"dir": "relative/path", "publisher": "...", "name": "..."}.

Why are publisher and name fields needed? In Cargo, as far as I understand, only path is used to specify the dependency and name is provided to be able to rename the dependency from the user's side.

[andrius-puksta-sensmetry]

Publisher and name are needed for a few reasons:

• consistent UX for different usage types: some usage types (git, index) require publisher+name for obtaining to correct project; others (src path, kpar path, URL) in principle don't, but the UX will be inconsistent if publisher/name are unknown
• not requiring publisher and name for all typed usages will have bad UX for:
  • dependency overrides
  • manual inspection of usage list (also info output): ../../some-dir/aaa/tmp/something is less informative than publisher = <pub>, name = <name>, dir = <dir>
  • error reporting, whenever it relies on usage specification
  • other tools, like IDEs: e.g. if imports are of the form publisher::name or something, not having publisher/name explicitly specified in .project.json would result in confusing (and unactionable) errors about unknown names if the usage is renamed/moved
• consistency with cargo: cargo does require name to match actual name; if a user wants to rename the dep, package = "original-name" must be specified. Note that Cargo has good reasons to do it this way; not all of them apply to us:
  • each use can be checked from just Cargo.toml (any identifier is fine for this, so the real name is not needed)
  • explicit intent to have that dependency: allows ensuring that the expected project is at the destination if renames/moves happen
  • simpler resolution implementation by having all the info upfront
  • better error reporting if duplicates of the same project from different sources are resolved
• simpler implementation, especially for error reporting
• push users to have publisher set to have typed usages
• simpler project sources deduplication/merging