feat: Multi-file contract analysis with inheritance and import graph resolution

[Nanle-code]

Overview

The current scanner treats each .sol file as an isolated unit. In real Solidity projects, contracts are deeply interconnected via inheritance (is), interface implementation, and library imports. Vulnerabilities that cross file boundaries — particularly in inherited functions and overridden modifiers — are entirely invisible to the current scanner.

Problem

// BaseVault.sol
contract BaseVault {
    function _authorizeUpgrade(address) internal virtual {} // no protection
}

// UpgradeableVault.sol
import "./BaseVault.sol";
contract UpgradeableVault is BaseVault, UUPSUpgradeable {
    // inherits unprotected _authorizeUpgrade — anyone can upgrade
}

Scanning UpgradeableVault.sol alone will not detect the vulnerability because the dangerous function body is in BaseVault.sol.

Proposed Solution

Phase 1: Import Graph Construction

1. Parse import statements from each file's AST to build a dependency graph
2. Resolve relative and node_modules paths to absolute file paths
3. Build a topological ordering of the import graph for processing order

Phase 2: Inheritance-Aware Analysis

1. When analyzing a contract C, collect all ancestor contracts via the inheritance chain
2. Merge function definitions, modifiers, and state variable declarations from ancestors
3. Apply rules against the merged contract view, not just the leaf contract
4. Tag findings with the origin file (definedIn: string) so reports point to the correct source location

Phase 3: Cross-File Dataflow

1. Track state variables defined in parent contracts
2. Track modifier definitions from parent contracts and apply them correctly when checking function guards in child contracts

New Fields on Finding

interface Finding {
  // ... existing fields
  definedIn?: string;       // File where the vulnerable code is defined
  inheritedBy?: string;     // File of the contract that inherits the vulnerability
  importPath?: string[];    // Resolved import chain
}

Acceptance Criteria

• Import graph builder in packages/core/src/ast/import-graph.ts
• Inheritance chain resolver merging ancestor contract members
• CP-107, CP-115, CP-116 rules updated to operate on the merged contract view
• definedIn and inheritedBy fields added to Finding type
• Multi-file example contracts in examples/contracts/multi-file/
• No performance regression >20% on single-file contracts
• Circular import detection with graceful warning (no infinite loop)