Brane Impact & Test Discovery

Comprehensive impact analysis and test discovery for Brane SDK changes.

Module Dependency Graph

brane-primitives (no deps)
       |
       v
   brane-core (depends on: primitives)
       |
       v
    brane-rpc (depends on: core, primitives)
       |
       v
  brane-contract (depends on: rpc, core, primitives)
       |
       v
  [Consumer modules: examples, benchmark, brane-smoke]

Impact Propagation Matrix

Quick Impact Analysis

Step 1: Identify Changed Files

# Recent commit
git diff --name-only HEAD~1 | grep '\.java$'

# Staged changes
git diff --cached --name-only | grep '\.java$'

# Working changes
git diff --name-only | grep '\.java$'

Step 2: Run Automated Analysis

# Full analysis with recommendations
./.claude/scripts/verify_change.sh

# Analyze specific file or class
./.claude/scripts/verify_change.sh Address
./.claude/scripts/verify_change.sh brane-core/src/main/java/sh/brane/core/types/Address.java

# Run with tests
./.claude/scripts/verify_change.sh --run

LSP-Enhanced Impact Analysis (Preferred)

Use cclsp MCP tools for precise, semantic impact analysis.

Why LSP > Grep

LSP Commands for Impact Analysis

# Find all usages of a symbol (MOST USEFUL)
mcp__cclsp__find_references(file_path, symbol_name)

# Find where a symbol is defined
mcp__cclsp__find_definition(file_path, symbol_name)

# Check for compile errors after changes
mcp__cclsp__get_diagnostics(file_path)

Example: Analyzing Impact of Changing Address.from()

# Step 1: Find all references to the method
mcp__cclsp__find_references(
  file_path="brane-core/src/main/java/sh/brane/core/types/Address.java",
  symbol_name="from"
)
→ Returns 47 locations across 12 files

# Step 2: Check if changes broke anything
mcp__cclsp__get_diagnostics(
  file_path="brane-core/src/main/java/sh/brane/core/types/Address.java"
)
→ Returns compile errors if signature is incompatible

When to Use LSP vs Grep

Test Discovery Commands (Fallback)

Find Tests for a Changed Class

CLASS_NAME="Address"

# Direct unit test (same name)
find . -path "*/test/*" -name "*${CLASS_NAME}*Test.java" | grep -v target

# All tests that reference this class (less precise than LSP)
grep -rl "$CLASS_NAME" --include="*Test.java" . | grep -v target

# Integration tests
grep -rl "$CLASS_NAME" --include="*IntegrationTest.java" . | grep -v target

# Examples (integration tests in examples module)
grep -rl "$CLASS_NAME" brane-examples/src/main/java --include="*.java" | grep -v target

Module-Specific Test Commands

Test Type Reference

Mandatory Test Layers

ALL THREE TEST LAYERS ARE MANDATORY. NEVER SKIP ANY.

Starting Anvil requires no special permission - just run anvil & in background.

Test Execution Order

Follow this order for every change:

Step 1: Unit Tests (Fast Feedback)

./gradlew :MODULE:test --tests "*ClassName*"
./gradlew :MODULE:test

Step 2: Downstream Unit Tests

./gradlew :downstream-module:test

Step 3: Integration Tests (Start Anvil First)

anvil &  # No permission needed
./scripts/test_integration.sh

Step 4: Smoke Tests

./scripts/test_smoke.sh

Full Verification (All at Once)

./verify_all.sh

Change Severity Categories

Note: Regardless of severity, ALL test layers (unit, integration, smoke) are MANDATORY.

HIGH Impact

• Changes to brane-primitives (foundation)
• Public API changes in brane-core (types, exceptions)
• Changes to sealed exception hierarchy
• Type signature changes (Address, Hash, Wei, HexData)

Action:

1. Unit: ./gradlew test (all modules)
2. Integration: ./scripts/test_integration.sh
3. Smoke: ./scripts/test_smoke.sh

MEDIUM Impact

• RPC client interface changes
• Contract binding logic changes
• Transaction builder changes
• Internal utility changes in core

Action:

1. Unit: Affected module + downstream modules
2. Integration: ./scripts/test_integration.sh
3. Smoke: ./scripts/test_smoke.sh

LOW Impact

• Private method changes
• Internal implementation details
• Test-only changes
• Documentation changes

Action:

1. Unit: Direct tests + module tests
2. Integration: ./scripts/test_integration.sh
3. Smoke: ./scripts/test_smoke.sh

Cross-Module Test Examples

When Address (brane-core) Changes

Direct:     brane-core/.../types/AddressTest.java
Dependent:  brane-core/.../abi/AbiEncoderTest.java
            brane-rpc/.../BraneTest.java
            brane-contract/.../BraneContractTest.java
Integration: brane-examples/.../TransferExample.java

When Brane (brane-rpc) Changes

Direct:     brane-rpc/.../BraneTest.java
Dependent:  brane-contract/.../BraneContractTest.java
Integration: brane-examples/.../*Example.java

When BraneContract (brane-contract) Changes

Direct:     brane-contract/.../BraneContractTest.java
Integration: brane-examples/.../ContractExample.java

Execution Instructions for Claude

When asked to analyze impact or find affected tests:

Phase 1: Identify Changes

1. Run git diff --name-only to find changed files
2. Extract module names from paths
3. Identify changed class/method names

Phase 2: LSP-Based Impact Analysis (PREFERRED)

For each changed public symbol, use LSP to find precise references:

mcp__cclsp__find_references(file_path, symbol_name)

This is MORE ACCURATE than grep because:

• No false positives from comments/strings
• Finds renamed imports and qualified references
• Shows exact line numbers

Example workflow:

# Changed file: Address.java, changed method: from()
mcp__cclsp__find_references(
  "brane-core/.../Address.java",
  "from"
)
→ 47 references in 12 files

# Check for compile errors
mcp__cclsp__get_diagnostics("brane-core/.../Address.java")
→ No errors (or shows what broke)

Phase 3: Determine Module Impact

1. Use the Impact Propagation Matrix to find affected modules
2. Categorize severity (HIGH/MEDIUM/LOW)
3. List transitive dependencies

Phase 4: Discover Tests

1. From LSP references, filter for *Test.java files
2. Find direct tests: find . -name "ClassNameTest.java"
3. Cross-reference with module dependency graph

Phase 5: Generate Report

Produce a report with:

• Changed files summary
• LSP reference count (e.g., "47 usages across 12 files")
• Impact severity assessment
• Affected tests (from LSP + file patterns)
• Recommended test commands (minimal → full)

Phase 6: Optionally Execute

If --run is specified:

./.claude/scripts/verify_change.sh --run

CI/CD Integration

For automated pipelines (all three layers mandatory):

# Determine changed modules
CHANGED_MODULES=$(git diff --name-only origin/main | grep -oE 'brane-[a-z]+' | sort -u)

# Layer 1: Unit tests for affected modules
for MODULE in $CHANGED_MODULES; do
    ./gradlew ":${MODULE}:test"
done

# Layer 2: Integration tests (always run)
./scripts/test_integration.sh

# Layer 3: Smoke tests (always run)
./scripts/test_smoke.sh

All three layers must pass for CI to be green.