Dependency Metadata

The dependency metadata is the layer that describes the relationship itself, on top of the two entities it connects. While from and to answer what are the two files involved?, the dependency metadata answers what is this dependency? — is it a type-only import, what is the structural relationship between the two elements, which specifiers does it bring in.

Unlike elements and files, there are no descriptors to configure for the dependency metadata. The plugin computes it automatically from the import: from the AST node that produced the dependency, the literal source string, and the relative position of the two elements.

This is the layer that lets you write policies about the nature of an import — for example, allowing a type-only dependency where a value dependency would be forbidden, or restricting imports to a child element.

Dependency Metadata Description

When the plugin analyzes a dependency, the dependency metadata is available as dependency, alongside the from and to entities. It has the following properties:

Property	Type	Description
source	<string>	The source string of the dependency as written in the code (for example "../helpers/data" or "react").
kind	<"value" | "type" | "typeof">	The dependency kind. A regular import is a value; a TypeScript import type is a type; an import typeof is a typeof.
nodeKind	<string | null>	The name of the AST dependency node that produced it (see boundaries/additional-dependency-nodes), or null.
specifiers	<array | null>	The imported or exported specifier names, or null when there are none.
relationship.from	<string | null>	What the importer is to the target, for example "parent" when the target is a direct child of the importer. One of "internal", "child", "descendant", "sibling", "parent", "uncle", "nephew", "ancestor". It is null when either side is not a known local element (for example an external package), or when the two elements have none of the relationships below, such as two top-level elements.
relationship.to	<string | null>	What the target is to the importer, for example "child" when the target is a direct child of the importer. It is the inverse of relationship.from.

Element Relationship

When both sides of a dependency are known local elements, the plugin computes the structural relationship between them from their positions in the element hierarchy. relationship.from says what the importer is to the target, and relationship.to what the target is to the importer, so each one is the inverse of the other:

relationship.from	relationship.to	Meaning
internal	internal	Both files belong to the same element.
parent	child	The target is a direct child of the importer.
ancestor	descendant	The target is nested deeper inside the importer.
sibling	sibling	Both elements share the same parent.
nephew	uncle	The target is a sibling of one of the importer's ancestors.
child	parent	The target is the direct parent of the importer.
descendant	ancestor	The importer is nested deeper inside the target.
uncle	nephew	The importer is a sibling of one of the target's ancestors.

Both relationship.from and relationship.to are null when either side is not a known local element (for example an external package or an unknown file), or when the two elements have none of these relationships, such as two top-level elements.

Matching Dependency Metadata using Selectors

To target a dependency by its metadata, use the dependency selector inside a policy, alongside the from and to entity selectors:

// Match type-only dependencies to helpers
{
  to: { element: { type: "helper" } },
  dependency: { kind: "type" }
}

// Match dependencies to a descendant element
{
  dependency: { relationship: { to: "descendant" } }
}

See Selectors → Dependency for the full dependency metadata selector reference.

Next Steps

• Selectors → Dependency - match dependency metadata in your policies.
• Policies - use from/to/dependency together with allow/disallow.
• Settings - configure which AST nodes produce dependencies.
• Classification - how the dependency metadata combines two entities into one dependency description.