Boundary Detector

THE killer feature. Find natural component boundaries in your codebase and know exactly where to cut when extracting components.

Analyzes the import/dependency graph to detect clusters of files that naturally belong together, identifies bridge files that connect multiple areas, finds isolated orphan files, and rates extraction risk for each component.

This is "one command that tells you where to cut."

Usage

CLI

python boundary_detector.py <project_path>
python boundary_detector.py <project_path> --output boundaries.json
python boundary_detector.py <project_path> --markdown
python boundary_detector.py <project_path> --min-cluster 3
python boundary_detector.py <project_path> --compact

MCP

drydock_boundaries(project_path: str, min_cluster: int = 2) -> str

Returns boundaries and component risk analysis as JSON.

Example Output

{
  "clusters": [
    {
      "id": 1,
      "common_prefix": "core-engine",
      "file_count": 12,
      "files": [
        "src/core/engine.py",
        "src/core/runner.py",
        "src/core/config.py",
        "src/core/utils.py"
      ],
      "cohesion": 0.94,
      "internal_edges": 23,
      "external_dep_count": 2,
      "external_deps": [
        "src/api",
        "src/logging"
      ]
    },
    {
      "id": 2,
      "common_prefix": "api-handlers",
      "file_count": 8,
      "files": [
        "src/api/handler.py",
        "src/api/router.py",
        "src/api/middleware.py"
      ],
      "cohesion": 0.87,
      "internal_edges": 15,
      "external_dep_count": 3,
      "external_deps": [
        "src/core",
        "src/auth",
        "src/db"
      ]
    },
    {
      "id": 3,
      "common_prefix": "db-models",
      "file_count": 5,
      "files": [
        "src/db/models.py",
        "src/db/schema.py",
        "src/db/migrations.py"
      ],
      "cohesion": 0.92,
      "internal_edges": 9,
      "external_dep_count": 1,
      "external_deps": [
        "src/core"
      ]
    }
  ],
  "bridges": [
    {
      "file": "src/main.py",
      "connects_dirs": ["core", "api", "db"],
      "connection_count": 3,
      "edge_count": 5
    },
    {
      "file": "src/bootstrap.py",
      "connects_dirs": ["core", "api"],
      "connection_count": 2,
      "edge_count": 3
    }
  ],
  "orphans": [
    "src/utils/helpers.py",
    "src/constants.py"
  ],
  "extraction_risks": {
    "core-engine": {
      "level": "low",
      "reason": "Minimal external dependencies (2), high internal cohesion (0.94)",
      "blocking_files": []
    },
    "api-handlers": {
      "level": "medium",
      "reason": "Moderate external dependencies (3), depends on core",
      "blocking_files": ["src/core/engine.py"]
    },
    "db-models": {
      "level": "low",
      "reason": "Single external dependency, highly cohesive",
      "blocking_files": []
    }
  },
  "summary": {
    "total_clusters": 3,
    "total_bridge_files": 2,
    "total_orphans": 2,
    "suggested_extraction_order": [
      "db-models (lowest risk)",
      "core-engine (low risk)",
      "api-handlers (medium risk)"
    ]
  }
}

Understanding the Output

Clusters: Groups of files that import each other heavily and form logical components.

Cohesion: Measure of how tightly files within a cluster are connected (0.0-1.0, higher is better). Values above 0.85 indicate natural boundaries.

Bridge Files: Files that connect multiple clusters. These are decision points—if you extract, you may need to modify bridges.

Orphans: Files with no or minimal connections. Usually safe to move, modify, or delete.

Extraction Risk: Assessment of difficulty to extract a component: - Low: Minimal external dependencies, clear boundaries - Medium: Some external dependencies but extractable - High: Heavy coupling, likely to break if extracted

Options

Flag	Type	Default	Description
project_path	positional	required	Path to project root
--output, -o	string	stdout	Output file path
--markdown, -m	flag	false	Output as Markdown instead of JSON
--min-cluster	int	2	Minimum files per cluster
--compact, -c	flag	false	Compact JSON (no indentation)