Add source code capture for exception traces

[philliphartin]

Add Source Code Capture for Exception Traces

This PR adds the ability to capture source code lines around exception locations in user-land code, providing developers with immediate context when debugging exceptions without needing to open files.

What's Changed

Configuration

• Added capture_exception_source_code configuration option (defaults to true)
• Can be controlled via NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE environment variable

Core Implementation

• Updated ExceptionSensor to capture source code context for user files in exception traces
• Added source code loading and line extraction functionality
• Only captures code from user-land files (excludes vendor, framework, and internal files)
• Captures ±5 lines of context around the exception location

API Changes

• Made Location::isVendorFile() and Location::isInternalFile() public
• Added Location::getBasePath() method for source code file resolution

Payload Preview

When an exception occurs in user code, the trace now includes a code field with source context:

{
  "trace": [
    {
      "file": "app/Mail/WelcomeEmail.php:28",
      "source": "Illuminate\\Mail\\Mailables\\Envelope->__construct(null, array, array, array, array, array)",
      "code": {
        "23": "    /**",
        "24": "     * Get the message envelope.",
        "25": "     */",
        "26": "    public function envelope(): Envelope",
        "27": "    {",
        "28": "        return new Envelope(",
        "29": "            subject: $this->subject,",
        "30": "        );",
        "31": "    }",
        "32": "",
        "33": "    /**"
      }
    },
    {
      "file": "app/Http/Controllers/UserController.php:45",
      "source": "Illuminate\\Mail\\PendingMail->send(App\\Mail\\WelcomeEmail)",
      "code": {
        "40": "    public function store(Request $request)",
        "41": "    {",
        "42": "        $user = User::create($request->validated());",
        "43": "",
        "44": "        try {",
        "45": "            Mail::to($user->email)->send(new WelcomeEmail($user));",
        "46": "        } catch (Exception $e) {",
        "47": "            report($e);",
        "48": "            return response()->json(['error' => 'Failed to send email'], 500);",
        "49": "        }",
        "50": ""
      }
    }
  ]
}

Benefits

1. Immediate Context: Once added to our UI, developers can see the exact code that caused the exception without switching to their IDE
2. Better Error Reports: Support teams get more context when investigating issues
3. Configurable: Can be disabled in production environments if desired for performance/security

Performance Considerations

• Only captures source code for user-land files (not vendor/framework code)
• Files are only loaded once into memory
• Can be disabled via configuration if needed
• Minimal overhead as it only activates when exceptions occur

Testing

• Added comprehensive test coverage for source code capture functionality
• Tests verify correct context extraction and proper filtering of vendor files
• Includes tests for configuration toggle

[faustbrian]

@philliphartin is there any ETA on when this could be expected to be released? That's the last thing before we could cancel our Sentry subscription.

[philliphartin]

Hey @faustbrian, we're eager to get this completed ASAP! Ideally next week.

[faustbrian]

@philliphartin any progress on this?