borghei/Claude-Skills / engineering/monorepo-navigator
monorepo-navigator
VerifiedManage and optimize monorepos with Turborepo, Nx, pnpm workspaces, and Changesets. Use when working in monorepos, running impact analysis, optimizing build times with remote caching, migrating from multi-repo, or coordinating publishing.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
| assets/sample_monorepo/apps/docs/package.json | manifest | 100 B |
| assets/sample_monorepo/apps/web/package.json | manifest | 161 B |
| assets/sample_monorepo/apps/web/src/page.tsx | other | 47 B |
| assets/sample_monorepo/package.json | manifest | 83 B |
| assets/sample_monorepo/packages/ui/package.json | manifest | 129 B |
| assets/sample_monorepo/packages/ui/src/button.tsx | other | 33 B |
| assets/sample_monorepo/packages/utils/package.json | manifest | 100 B |
| assets/sample_monorepo/packages/utils/src/index.ts | script | 55 B |
| assets/sample_monorepo/pnpm-workspace.yaml | config | 40 B |
| references/operations-and-best-practices.md | markdown | 4.3 KB |
| references/tooling-and-configuration.md | markdown | 8.4 KB |
| scripts/dependency_graph.pyexecutable | script | 16.4 KB |
| scripts/impact_detector.pyexecutable | script | 14.5 KB |
| scripts/package_analyzer.pyexecutable | script | 14.9 KB |
scripts/impact_detector.py
View on GitHub#!/usr/bin/env python3
"""
Impact Detector - Determine which monorepo packages are affected by file changes.
Given a list of changed files (or a git ref to diff against), this tool resolves
which packages are directly affected, then computes transitive dependents to
show the full blast radius. Useful for selective CI builds and PR impact summaries.
License: MIT
"""
import argparse
import glob
import json
import os
import subprocess
import sys
from collections import deque
from dataclasses import dataclass, field, asdict
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple
@dataclass
class ImpactResult:
"""Result of impact analysis."""
changed_files: List[str]
directly_affected: List[str]
transitively_affected: List[str]
total_affected: List[str]
unaffected: List[str]
blast_radius_percent: float
impact_chains: Dict[str, List[str]]
root_config_changed: bool
warnings: List[str]
class MonorepoGraph:
"""Builds and queries the internal dependency graph."""
def __init__(self, root_path: str):
self.root_path = Path(root_path).resolve()
self.packages: Dict[str, str] = {} # name -> relative path
self.paths_to_names: Dict[str, str] = {} # relative path -> name
self.deps: Dict[str, Set[str]] = {} # name -> set of internal deps
self.reverse_deps: Dict[str, Set[str]] = {} # name -> set of dependents
self.warnings: List[str] = []
def build(self) -> None:
"""Discover packages and build the dependency graph."""
workspace_globs = self._detect_workspaces()
if not workspace_globs:
workspace_globs = ["packages/*", "apps/*", "libs/*", "modules/*"]
self.warnings.append("No workspace config found; using default glob patterns.")
self._discover_packages(workspace_globs)
self._build_graph()
def _detect_workspaces(self) -> List[str]:
"""Detect workspace globs from config files."""
# pnpm-workspace.yaml
pnpm_ws = self.root_path / "pnpm-workspace.yaml"
if pnpm_ws.exists():
return self._parse_pnpm_workspace(pnpm_ws)
# package.json workspaces
root_pkg = self.root_path / "package.json"
if root_pkg.exists():
try:
with open(root_pkg, "r") as f:
data = json.load(f)
ws = data.get("workspaces")
if isinstance(ws, list):
return ws
if isinstance(ws, dict) and "packages" in ws:
return ws["packages"]
except (json.JSONDecodeError, OSError):
pass
# lerna.json
lerna_cfg = self.root_path / "lerna.json"
if lerna_cfg.exists():
try:
with open(lerna_cfg, "r") as f:
return json.load(f).get("packages", ["packages/*"])
except (json.JSONDecodeError, OSError):
pass
return []
def _parse_pnpm_workspace(self, filepath: Path) -> List[str]:
"""Parse pnpm-workspace.yaml without external YAML library."""
globs = []
try:
with open(filepath, "r") as f:
in_packages = False
for line in f:
stripped = line.strip()
if stripped == "packages:":
in_packages = True
continue
if in_packages:
if stripped.startswith("- "):
globs.append(stripped[2:].strip().strip("'\""))
elif stripped and not stripped.startswith("#"):
break
except OSError:
pass
return globs
def _discover_packages(self, workspace_globs: List[str]) -> None:
"""Find all packages matching workspace globs."""
for ws_glob in workspace_globs:
if ws_glob.startswith("!"):
continue
pattern = str(self.root_path / ws_glob / "package.json")
for pkg_path in sorted(glob.glob(pattern)):
pkg_json = Path(pkg_path)
try:
with open(pkg_json, "r") as f:
data = json.load(f)
except (json.JSONDecodeError, OSError):
continue
name = data.get("name")
if not name:
continue
rel_path = str(pkg_json.parent.relative_to(self.root_path))
self.packages[name] = rel_path
self.paths_to_names[rel_path] = name
def _build_graph(self) -> None:
"""Build dependency and reverse-dependency maps."""
internal_names = set(self.packages.keys())
for name, rel_path in self.packages.items():
pkg_json = self.root_path / rel_path / "package.json"
try:
with open(pkg_json, "r") as f:
data = json.load(f)
except (json.JSONDecodeError, OSError):
continue
all_dep_sections = [
data.get("dependencies", {}),
data.get("devDependencies", {}),
data.get("peerDependencies", {}),
]
internal_deps = set()
for section in all_dep_sections:
for dep_name in section:
if dep_name in internal_names:
internal_deps.add(dep_name)
self.deps[name] = internal_deps
for dep in internal_deps:
self.reverse_deps.setdefault(dep, set()).add(name)
def get_package_for_file(self, filepath: str) -> Optional[str]:
"""Determine which package a file belongs to based on path prefix."""
# Normalize path
normalized = filepath.replace("\\", "/").lstrip("./")
# Sort paths longest first for most specific match
sorted_paths = sorted(self.paths_to_names.keys(), key=len, reverse=True)
for pkg_path in sorted_paths:
if normalized.startswith(pkg_path + "/") or normalized == pkg_path:
return self.paths_to_names[pkg_path]
return None
def get_transitive_dependents(self, package_name: str) -> List[str]:
"""BFS to find all transitive dependents of a package."""
visited: Set[str] = set()
queue = deque([package_name])
result = []
while queue:
current = queue.popleft()
for dependent in self.reverse_deps.get(current, set()):
if dependent not in visited:
visited.add(dependent)
result.append(dependent)
queue.append(dependent)
return sorted(result)
def get_impact_chain(self, source: str, target: str) -> List[str]:
"""Find the shortest dependency chain from source to target (via reverse deps)."""
if source == target:
return [source]
visited: Set[str] = {source}
queue: deque = deque([(source, [source])])
while queue:
current, path = queue.popleft()
for dep in self.reverse_deps.get(current, set()):
if dep == target:
return path + [dep]
if dep not in visited:
visited.add(dep)
queue.append((dep, path + [dep]))
return []
ROOT_CONFIG_FILES = {
"turbo.json", "pnpm-workspace.yaml", "lerna.json", "nx.json",
"tsconfig.json", "tsconfig.base.json", ".eslintrc.js", ".eslintrc.json",
"jest.config.js", "vitest.config.ts", "pnpm-lock.yaml", "yarn.lock",
"package-lock.json",
}
def get_changed_files_from_git(root_path: str, ref: str) -> List[str]:
"""Get list of changed files compared to a git ref."""
try:
result = subprocess.run(
["git", "diff", "--name-only", ref],
capture_output=True,
text=True,
cwd=root_path,
timeout=30,
)
if result.returncode != 0:
# Try with merge-base
merge_base = subprocess.run(
["git", "merge-base", ref, "HEAD"],
capture_output=True,
text=True,
cwd=root_path,
timeout=15,
)
if merge_base.returncode == 0:
base = merge_base.stdout.strip()
result = subprocess.run(
["git", "diff", "--name-only", base],
capture_output=True,
text=True,
cwd=root_path,
timeout=30,
)
return [f for f in result.stdout.strip().split("\n") if f]
except (subprocess.TimeoutExpired, FileNotFoundError):
return []
def detect_impact(
root_path: str,
changed_files: List[str],
) -> ImpactResult:
"""Run impact detection on the given changed files."""
graph = MonorepoGraph(root_path)
graph.build()
all_package_names = set(graph.packages.keys())
directly_affected: Set[str] = set()
root_config_changed = False
for filepath in changed_files:
basename = os.path.basename(filepath)
if basename in ROOT_CONFIG_FILES or filepath.startswith(".github/"):
root_config_changed = True
pkg_name = graph.get_package_for_file(filepath)
if pkg_name:
directly_affected.add(pkg_name)
# Compute transitive dependents
transitively_affected: Set[str] = set()
for pkg in directly_affected:
for dep in graph.get_transitive_dependents(pkg):
if dep not in directly_affected:
transitively_affected.add(dep)
total_affected = directly_affected | transitively_affected
# If root config changed, all packages are affected
if root_config_changed:
total_affected = all_package_names
transitively_affected = all_package_names - directly_affected
unaffected = sorted(all_package_names - total_affected)
# Build impact chains for transitively affected packages
impact_chains: Dict[str, List[str]] = {}
for target in sorted(transitively_affected):
for source in sorted(directly_affected):
chain = graph.get_impact_chain(source, target)
if chain:
impact_chains[target] = chain
break
total_count = len(all_package_names) if all_package_names else 1
blast_pct = round(len(total_affected) / total_count * 100, 1)
return ImpactResult(
changed_files=changed_files,
directly_affected=sorted(directly_affected),
transitively_affected=sorted(transitively_affected),
total_affected=sorted(total_affected),
unaffected=unaffected,
blast_radius_percent=blast_pct,
impact_chains=impact_chains,
root_config_changed=root_config_changed,
warnings=graph.warnings,
)
def format_human(result: ImpactResult) -> str:
"""Format impact result for human-readable output."""
lines = []
lines.append("=" * 60)
lines.append("IMPACT ANALYSIS")
lines.append("=" * 60)
lines.append(f"Changed files: {len(result.changed_files)}")
lines.append(f"Blast radius: {result.blast_radius_percent}%")
if result.root_config_changed:
lines.append("Root config changed: YES (all packages affected)")
lines.append("")
lines.append("-" * 60)
lines.append(f"DIRECTLY AFFECTED ({len(result.directly_affected)})")
lines.append("-" * 60)
for pkg in result.directly_affected:
lines.append(f" * {pkg}")
lines.append("")
if result.transitively_affected:
lines.append("-" * 60)
lines.append(f"TRANSITIVELY AFFECTED ({len(result.transitively_affected)})")
lines.append("-" * 60)
for pkg in result.transitively_affected:
chain = result.impact_chains.get(pkg, [])
chain_str = f" (via {' -> '.join(chain)})" if chain else ""
lines.append(f" ~ {pkg}{chain_str}")
lines.append("")
if result.unaffected:
lines.append("-" * 60)
lines.append(f"UNAFFECTED ({len(result.unaffected)})")
lines.append("-" * 60)
for pkg in result.unaffected:
lines.append(f" {pkg}")
lines.append("")
if result.warnings:
lines.append("-" * 60)
lines.append("WARNINGS")
lines.append("-" * 60)
for w in result.warnings:
lines.append(f" ! {w}")
lines.append("")
return "\n".join(lines)
def main() -> None:
parser = argparse.ArgumentParser(
description="Detect which monorepo packages are affected by file changes.",
epilog="Example: python impact_detector.py --ref origin/main --json",
)
parser.add_argument(
"path",
nargs="?",
default=".",
help="Path to monorepo root (default: current directory)",
)
parser.add_argument(
"--files",
nargs="+",
help="Explicit list of changed file paths (relative to monorepo root)",
)
parser.add_argument(
"--ref",
default=None,
help="Git ref to diff against (e.g., origin/main, HEAD~3)",
)
parser.add_argument(
"--json",
action="store_true",
dest="json_output",
help="Output results as JSON",
)
parser.add_argument(
"--affected-only",
action="store_true",
help="Only print names of affected packages (one per line)",
)
args = parser.parse_args()
root = Path(args.path).resolve()
if not root.is_dir():
print(f"Error: {root} is not a valid directory", file=sys.stderr)
sys.exit(2)
# Determine changed files
changed_files: List[str] = []
if args.files:
changed_files = args.files
elif args.ref:
changed_files = get_changed_files_from_git(str(root), args.ref)
if not changed_files:
print(f"No changed files found compared to {args.ref}", file=sys.stderr)
sys.exit(0)
else:
# Read from stdin
if not sys.stdin.isatty():
changed_files = [line.strip() for line in sys.stdin if line.strip()]
else:
print("Error: Provide --files, --ref, or pipe file list via stdin", file=sys.stderr)
parser.print_help(sys.stderr)
sys.exit(2)
result = detect_impact(str(root), changed_files)
if args.json_output:
print(json.dumps(asdict(result), indent=2))
elif args.affected_only:
for pkg in result.total_affected:
print(pkg)
else:
print(format_human(result))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |