How nerdwalletoss/shepherd works
Main Components
• CLI Interface: The entry point (src/cli.ts) that parses commands (e.g., checkout, apply, commit, push, pr-preview, pr) and delegates work.
• Command Modules: Each subcommand (residing in src/commands) handles specific operations. For example, the “checkout” command not only clones repositories but also uses hooks to determine eligibility.
• Adapters: Found in src/adapters, these modules abstract away differences in version control systems (currently focusing on Git/GitHub). They handle repository searches, cloning operations, and API interactions.
• Services: Located in src/services (like the GitHub service), these components provide higher-level operations supporting the adapters.
• Migration Spec / Hooks Engine: Shepherd’s core logic centers around interpreting a migration spec (shepherd.yml) with various hooks (should_migrate, post_checkout, apply, pr_message). This part ties into the commands to decide whether and how to perform changes.
• Logger & Utilities: (src/logger and src/util) which help in error reporting, logging progress, and executing shell commands across repositories.
• Configuration & Environment Management: Environment variables (e.g., SHEPHERD_GITHUB_REPO_NAME, SHEPHERD_REPO_DIR) and configuration files (babel, tsconfig, ESLint config) that influence run-time behavior.
Interactions and Relationships
• The CLI parses arguments and invokes the respective command module.
• Each command (e.g., “checkout”, “apply”, “commit”) calls into:
• The Hook Executor that runs commands from the migration spec.
• The Adapter module to interact with Git repositories and, where necessary, GitHub API.
• Utility libraries to execute shell commands and perform file operations.
• From CLI → Command Modules → Adapters/Services → External Systems (e.g., Git, GitHub APIs)
• Hooks execute in a sequence where “should_migrate” determines eligibility, “post_checkout” sets up the repo, “apply” effects the change, and “pr_message” dynamically creates the PR description.
• Environment variables and the persisted state mechanism (via SHEPHERD_DATA_DIR) influence command processing.
Architectural Patterns & Design Principles
• Modular Design: The structure separates concerns into CLI parsing, command execution, version control handling, and utility functions.
• Adapter Pattern: The “adapter” folder and related services abstract external systems like GitHub so that the core migration logic doesn’t depend on a specific version control system.
• Declarative Configuration: Using the YAML migration spec (shepherd.yml), Shepherd follows a declarative approach where the “what to do” is separated from the “how to do it.”
• Command Pattern: Each operational step (checkout, apply, commit, etc.) is implemented as a discrete command module, ensuring clear separation of functionality.
• Optionally, include separate sections for “Development/Testing” components like E2E tests, examples, and fixtures to underscore comprehensive test coverage and sample migrations.