skills.rest
DataDog
DataDogOFFICIAL
Explore all skills by this author →
Website𝕏@datadoghqGitHub

dependency-direction-analysis

Detects layering violations in ddtrace module dependencies and proposes architectural fixes.

650|546|Updated Jun 20, 2016
Search Tags:#dependency analysis#Python#Refactoring#ci#ARCHITECTURE#layering violations#ddtrace
One-click install
npx skills add https://github.com/DataDog/dd-trace-py --skill dependency-direction-analysis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dependency-direction-analysis
Source: https://github.com/DataDog/dd-trace-py/tree/main/.claude/skills/dependency-direction-analysis
Command: npx skills add https://github.com/DataDog/dd-trace-py --skill dependency-direction-analysis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires uv.

What problem does it solve?

When contributing to dd-trace-py, imports that cross architectural boundaries (foundation code depending on products, or products depending on each other) create hidden coupling and circular-import risk. This Skill runs the dependency direction detector locally, interprets its output, and guides you through structurally sound fixes so the detect_layering_violations CI job passes.

Core Features & Use Cases

  • Violation Detection: Runs scripts/import-analysis/layers.py to analyze the codebase and produce a violations.json report with severity scores, zone classifications, and tangle indicators.
  • CI Comparison: Compares PR results against a base-branch snapshot to distinguish new, pre-existing, worsened, and removed violations, plus uncovered top-level modules.
  • Architectural Fix Patterns: Provides five concrete remediation patterns (core event bus, dependency inversion, shared-type extraction, code relocation, foundation demotion) with a decision checklist, explicitly forbidding deferred imports as a fix.
  • Use Case: Your PR fails the detect_layering_violations CI job because ddtrace.internal.tracemethods imports ddtrace.trace. Use this Skill to reproduce the violation locally, identify the exact cross-boundary names, and apply the appropriate restructuring pattern.

Quick Start

Run the dependency direction detector on my branch and propose fixes for any new layering violations it reports.

Frequently Asked Questions about dependency-direction-analysis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check for dependency layering violations in dd-trace-py?▼

Run uv run --script scripts/import-analysis/layers.py analyze violations.json from the repository root. This writes violations and uncovered modules to violations.json and prints a summary, requiring uv installed on your PATH.

How do I compare layering violations against the base branch like CI does?▼

Generate a violations.json on the base branch and one on your PR branch, then run uv run --script scripts/import-analysis/layers.py compare violations-base.json violations-pr.json. The output classifies violations as new, pre-existing, worsened, or removed.

What does an uncovered top-level module error mean in layers.json?▼

It means a new direct child of the ddtrace package was added without a zone assignment in scripts/import-analysis/layers.json. Resolve it by mapping it to a product zone, adding it to foundation.top_level, or assigning it to an existing product's carve-out.

Can I fix a layering violation with a deferred import inside a function?▼

No. Deferred imports are explicitly forbidden because they hide the structural problem and add runtime cost on every call. Use the documented patterns instead: core event bus, dependency inversion, shared-type extraction, or moving the code to the owning zone.

When should I add an exception to layers.json instead of fixing code?▼

Only when the cross-zone dependency is intentional and durable, such as contrib integrations depending on the tracing product by design. This is an architecture decision for human reviewers, not a shortcut to make CI pass.

Related Skills

Explore More Software Engineering Skills→
forbotsakeforbotsake
5

forbotsake-upgrade

Detect git or vendored installs and upgrade forbotsake with changelog summaries.

Official
Advanced
zorgentechzorgentech

merge-request

Resolves GitHub pull requests by orchestrating checks, threads, fixes, merges via gh CLI.

Official
Advanced
tylerbutlertylerbutler

fix-circular-deps

Resolve circular dependency and layer-check violations in the FluidFramework repository.

Community
Advanced
pax-kpax-k
3

architecture-boundary-enforcer

Enforce and document architecture boundaries using dependency-cruiser, ESLint, import-linter, and custom scripts.

Community
Advanced