Impact Detection Tool

The Impact Detection tool (noodlbox_detect_impact) analyzes your git changes and identifies which code symbols and processes are affected. This helps you understand the full scope of your changes before committing.

Parameters

Parameter	Type	Required	Description
`repository`	string	Yes	Repository name to analyze
`base_ref`	string	No	Base reference for comparison (default: "HEAD")
`change_scope`	string	No	What changes to analyze (default: "unstaged")
`include_content`	boolean	No	Include symbol signatures (default: false)
`max_processes`	number	No	Processes per page (1-50, default: 10)
`page`	number	No	Page number for pagination (0-based, default: 0)

Change Scopes

The change_scope parameter determines which changes to analyze:

Scope	Description	Use Case
`unstaged`	Uncommitted changes not staged	See impact before staging
`staged`	Changes staged for commit	Review before committing
`all`	Both staged and unstaged	Complete picture of working directory
`compare`	Compare base_ref with working tree	Analyze against specific commit/branch

Basic Usage

Check Unstaged Changes

{
  "repository": "my-app",
  "change_scope": "unstaged"
}

Review Staged Changes

{
  "repository": "my-app",
  "change_scope": "staged"
}

Compare Against Branch

{
  "repository": "my-app",
  "base_ref": "main",
  "change_scope": "compare"
}

Response Format

interface ImpactDetectionResult {
  changed_files: ChangedFile[];
  affected_processes: AffectedProcess[];
  total_processes: number;
  page: number;
  has_more: boolean;
}

interface ChangedFile {
  file_path: string;
  change_type: 'added' | 'modified' | 'deleted';
  lines_added: number;
  lines_deleted: number;
  affected_symbols: string[];
}

interface AffectedProcess {
  process_id: string;
  process_label: string;
  process_type: 'intra_community' | 'cross_community';
  affected_symbols: AffectedSymbol[];
}

interface AffectedSymbol {
  symbol_name: string;
  symbol_type: string;
  file_path: string;
  line_number?: number;
  change_type: 'modified' | 'potentially_affected';
  content?: string;  // If include_content is true
}

Example Response

{
  "changed_files": [
    {
      "file_path": "src/auth/login.ts",
      "change_type": "modified",
      "lines_added": 15,
      "lines_deleted": 3,
      "affected_symbols": ["authenticateUser", "validateCredentials"]
    }
  ],
  "affected_processes": [
    {
      "process_id": "auth_flow_123",
      "process_label": "UserAuthentication",
      "process_type": "intra_community",
      "affected_symbols": [
        {
          "symbol_name": "authenticateUser",
          "symbol_type": "Function",
          "file_path": "src/auth/login.ts",
          "line_number": 45,
          "change_type": "modified"
        },
        {
          "symbol_name": "checkPermissions",
          "symbol_type": "Function",
          "file_path": "src/auth/permissions.ts",
          "line_number": 89,
          "change_type": "potentially_affected"
        }
      ]
    }
  ],
  "total_processes": 1,
  "page": 0,
  "has_more": false
}

Understanding Impact

Change Types

modified

Symbol was directly changed in your git diff.

{
  "symbol_name": "login",
  "change_type": "modified",
  "file_path": "src/auth.ts"
}

potentially_affected

Symbol calls or is called by a modified symbol, so it may be affected.

{
  "symbol_name": "authorize",
  "change_type": "potentially_affected",
  "file_path": "src/middleware.ts"
}

Process Types

intra_community

Process operates within a single code community. Changes are more localized.

cross_community

Process spans multiple communities. Changes may have wider impact.

Workflows

Pre-Commit Review

Check impact before staging changes:

{
  "repository": "my-app",
  "change_scope": "unstaged",
  "include_content": false
}

Review:

Which files changed
Which symbols modified
Which processes affected
Unexpected impacts

Pre-Push Validation

Review all local changes before pushing:

{
  "repository": "my-app",
  "base_ref": "origin/main",
  "change_scope": "compare",
  "max_processes": 50
}

Feature Branch Analysis

Compare feature branch against main:

{
  "repository": "my-app",
  "base_ref": "main",
  "change_scope": "compare"
}

Advanced Usage

Pagination

For large changes, use pagination:

{
  "repository": "my-app",
  "max_processes": 10,
  "page": 0  // First page
}

Check has_more in response to see if more pages exist.

Include Symbol Content

Get symbol signatures to understand changes:

{
  "repository": "my-app",
  "change_scope": "staged",
  "include_content": true
}

Symbol content shows function signatures, class definitions, etc., not full file contents.

Use Cases

1. Breaking Change Detection

Identify if your changes might break dependent code:

{
  "repository": "api-server",
  "change_scope": "all"
}

Look for:

Modified public APIs
Changed function signatures
Altered data structures
Cross-community impacts

2. Test Coverage Planning

Determine which tests need updating:

{
  "repository": "frontend",
  "change_scope": "staged"
}

Affected processes indicate which test suites to run.

3. Code Review Preparation

Understand full scope before requesting review:

{
  "repository": "my-app",
  "base_ref": "develop",
  "change_scope": "compare",
  "max_processes": 100
}

Include comprehensive impact analysis in PR description.

4. Refactoring Safety

Verify refactoring doesn't have unexpected side effects:

{
  "repository": "core-lib",
  "change_scope": "unstaged",
  "include_content": true
}

Best Practices

1. Run Before Staging

Always check unstaged changes first:

# Make changes
# Run impact detection
# Review impact
# Stage changes
# Run impact detection again on staged
# Commit

2. Watch for Cross-Community Impact

Cross-community processes indicate wider impact:

{
  "affected_processes": [
    {
      "process_type": "cross_community",  // Pay attention
      "process_label": "DataSync"
    }
  ]
}

3. Use Pagination for Large Changes

Don't overwhelm yourself with huge result sets:

{
  "max_processes": 10,
  "page": 0
}

Review in manageable chunks.

4. Compare Against Target Branch

Before creating PR, compare against target:

{
  "base_ref": "main",
  "change_scope": "compare"
}

Troubleshooting

No Changes Detected

Verify you have uncommitted changes
Check change_scope matches your git state
Ensure you're in a git repository
Try change_scope: "all"

Too Many Results

Use pagination (max_processes, page)
Focus on specific scope (staged vs all)
Filter to specific base ref

Missing Expected Impact

Symbol might not be in knowledge graph yet
Re-index repository if needed
Check if file is tracked by git

Unexpected Processes Affected

This might indicate:

Hidden dependencies you weren't aware of
Need to update additional tests
Opportunity to refactor tight coupling

Performance Tips

Start without content: Set include_content: false initially
Use pagination: Don't fetch all processes at once
Narrow scope: Use staged instead of all when possible
Specific base ref: Compare against recent commits, not ancient history

Git Integration

The tool uses git2 (libgit2) to analyze changes:

Accurate line mapping
Works with any git workflow
Supports all git operations (merge, rebase, cherry-pick)
Handles binary files gracefully

Cypher Query Tool - Query affected symbols
Process Trace Resource - Understand process flows
Refactoring - Safe refactoring workflows

On this page