Crate cabin_explain 

Typed dependency-tree and explain models for cabin tree and cabin explain.

cabin metadata already exposes the loaded package state as a deterministic JSON document. This crate adds two complementary, lower-bandwidth views on the same loaded PackageGraph + lockfile + active patch / source-replacement state:

• build_tree returns a TreeNode showing every package in the loaded PackageGraph reachable from the selected primary packages, with edges tagged by cabin_core::DependencyKind and provenance pulled from the lockfile / active patch set. Renderers (render_tree_human / render_tree_json) turn the typed tree into either a stable text drawing or a structured JSON document; the JSON document shares its package shape with cabin metadata.

• explain_package / explain_target / explain_source / explain_feature / explain_build_config each return a typed Explanation answering “why is X selected”, “where does X come from”, “which feature lit up X”, and “what does the build configuration look like for X”. Each variant carries only structured data so callers can render either a human-readable summary (render_explanation_human) or a stable JSON document (render_explanation_json).

Crate boundaries:

• this crate must not run the resolver, parse manifests, or plan builds; it consumes the typed values the orchestration layer hands it;
• it must not perform I/O. The orchestration layer in cabin is responsible for loading the workspace, the lockfile, and the active patch set; this crate works purely on those typed inputs;
• it must not invent new identity for packages. Provenance comes from cabin_workspace::PackageKind, the lockfile, the patch set, and the source-replacement settings.

Determinism contract

Every output produced by this crate is deterministic across runs:

• tree children are sorted by (dependency_kind, package_name, package_version);
• explanation paths are sorted by (length, joined name sequence);
• JSON keys are emitted in struct-declaration order;
• paths surfaced through the API are not normalized here — that is the orchestration layer’s job.

Anything that mutates the inputs is the orchestration layer’s responsibility; this crate only reads them.

Modules

cabin_feature_per_package_view

Stand-in module that names the per-package feature view this crate consumes through a thin &FeatureView parameter. The orchestration layer (cabin) already builds the typed cabin_feature::FeatureResolution; rather than depending on the full crate from a query-only library, we accept an abstract view object so the orchestration layer can adapt the existing types into our shape without leaking the resolver crate boundary.

Structs

ExplainStep

One step in a PackageExplanation::paths chain.

FeatureExplanation

Explain a feature’s enablement: declared, enabled, what it implies, and which root pulled it in if any.

PackageExplanation

Explain why a package is in the resolved graph, who pulled it in, and which dependency edge introduced it.

SourceExplanation

Explain where a package’s source bytes came from.

TargetExplanation

Explain a target’s owning package, kind, language summary, and dependency edges. cabin explain target <name> only considers targets in the selected package closure.

TreeInputs

Per-call options for build_tree. Mirrors the same dependency-kind filter cabin tree --kind ... exposes, plus the optional Lockfile / patch / vendor / source-replacement inputs used to color provenance.

TreeNode

One node in a dependency tree rooted at a selected primary package. Children are deduplicated per traversal: the first occurrence of a (name, version) carries the full subtree; subsequent occurrences are marked with TreeNode::repeated.

Enums

ExplainError

Errors produced by the explain queries. Wording is stable so integration tests can match on substrings.

Explanation

Typed explanation chain returned by every cabin explain query. Renderers read the variant to choose the layout; the JSON output is a tagged union so downstream tooling sees the query kind without re-parsing.

SourceProvenance

Provenance label for one node in a TreeNode or one step in an Explanation::Package chain.

Functions

build_tree

Build a deterministic TreeNode forest rooted at every index in roots. Returned as a single root-less synthetic vector with the documented sort key applied at every level so renderers can iterate without re-sorting.

explain_build_config

cabin explain build-config <package> returns the package’s resolved cabin_core::BuildConfiguration. The orchestration layer already knows how to render it through BuildConfiguration::as_json, so this crate just looks it up.

explain_feature

Build a FeatureExplanation for package/feature. The query string must contain a single / separating the package name from the feature name; an unrecognized shape is rejected with ExplainError::InvalidFeatureQuery.

explain_package

Build a PackageExplanation for name. Returns ExplainError::PackageNotFound when the name is not in the resolved graph; returns ExplainError::AmbiguousPackageName if a future graph gains multiple packages with the same name from distinct sources (today the resolver enforces unique names).

explain_source

Build a SourceExplanation for the named package.

explain_target

Build a TargetExplanation for target_name, scoped to the selected packages. Returns ExplainError::TargetNotFound if the name does not exist in any selected package, with a list of candidate names for the diagnostic.

render_explanation_human

Render an Explanation as a concise human-readable summary suitable for terminal output.

render_explanation_json

Render an Explanation as a stable JSON document.

render_tree_human

Render a TreeNode forest as a human-readable Unicode drawing. Output is deterministic: every level sorts by (edge_kind, name, version) before this rendering runs, so callers can compare two renderings byte-for-byte.

render_tree_json

Render the forest as a stable JSON document.