Architecture Drift Check

Run erode check against local changes to detect undeclared dependencies and architecture violations before pushing.

When to Activate

Run this check proactively:

1. After adding new integrations -- run when you write code that introduces new imports, API calls, database connections, message queue producers/consumers, or service-to-service communication
2. Before committing -- run before creating any commit to verify no drift was introduced during the session
3. On request -- run when the user mentions "architecture check", "drift check", or "erode"

Skip this check for changes that cannot introduce new dependencies:

• Documentation-only changes (no code paths affected)
• Test-only changes (test code is not part of the production architecture)
• Config/tooling changes like tsconfig, eslint, or prettier (no runtime dependencies)
• Refactors that modify existing logic without adding external calls

How to Run

Choose the mode based on git state:

Unstaged changes exist (you just wrote code):

npx @erode-app/cli check --format json

Changes are staged (ready to commit):

npx @erode-app/cli check --format json --staged

Commits exist on the branch (ready to push):

npx @erode-app/cli check --format json --branch main

The model path is read from .eroderc.json (adapter.modelPath). Pass <model-path> as a positional argument to override it.

Add --fail-on-violations when you want a non-zero exit code on drift.

The repository URL is auto-detected from the git remote. Use --repo <url> only if auto-detection fails.

Interpreting Results

Parse the JSON output. The key fields are:

• status: "success" (no drift), "violations" (drift found), or "error"
• analysis.violations[]: each violation has severity (high, medium, low), description, file, line, and suggestion
• analysis.summary: human-readable overview
• analysis.modelUpdates: suggested relationship changes for the architecture model
• dependencyChanges[]: each entry has type (added, removed, modified), dependency, file, and description -- use this to explain what dependency changes were detected

When violations are found

1. Read each violation and its suggestion
2. Decide the right fix -- either:
   • Refactor the code to use the declared dependency path (e.g., call through an API gateway instead of directly)
   • Or note that the architecture model needs updating (the dependency is intentional but undeclared)
3. Tell the user what you found, the severity, and your recommended fix
4. Do not silently suppress violations -- always surface them

When no violations are found

Briefly confirm: "Architecture check passed, no undeclared dependencies detected."

When the command fails

If erode check exits with an error, read the error message. Common causes: the AI provider API key is not set, the model path in .eroderc.json does not exist, or there is no git remote configured. Report the error to the user with the suggested fix from the error message.

Configuration

The model path and provider are read from .eroderc.json at the repository root. API keys come from environment variables (ERODE_GEMINI_API_KEY, ERODE_OPENAI_API_KEY, or ERODE_ANTHROPIC_API_KEY).