Capture code snippet from diagnostic compiler output #9362

bripeticca · 2025-11-11T17:13:25Z

This PR refactors diagnostic handling in the Swift build system by introducing a dedicated message handler and per-task output buffering to properly parse and emit compiler diagnostics individually.

Key Changes

SwiftBuildSystemMessageHandler

Introduced a new dedicated handler class to process SwiftBuildMessage events from the build operation
Moved message handling logic out of inline nested functions for better organization and testability
Maintains build state, progress animation, and diagnostic processing in a single cohesive component

Per-Task Data Buffering

Added taskDataBuffer struct in BuildState to capture compiler output per task signature
New TaskDataBuffer struct allows for using LocationContext or LocationContext2 as a subscript key to fetch the appropriate data buffer for a task, defaulting to the global buffer if no associated task or target can be identified.
Task output is accumulated in the buffer as .output messages arrive
Buffer contents are processed when tasks complete, ensuring all output is captured before parsing
Failed tasks with no useful or apparent message will be demoted to an info log level to avoid creating too much noise on the output.

* Built tentative test class SwiftBuildSystemOutputParser to handle the compiler output specifically * Added a handleDiagnostic method to possibly substitute the emitEvent local scope implementation of handling a SwiftBuildMessage diagnostic

* the flag `appendToOutputStream` helps us to determine whether a diagnostic is to be emitted or whether we'll be emitting the compiler output via OutputInfo * separate the emitEvent method into the SwiftBuildSystemMessageHandler

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

bripeticca · 2025-11-20T19:08:16Z

@swift-ci please test

owenv

Thie generally lgtm but I have some concerns about the regex-based parsing when we emit the textual compiler output.

Perf - It's important this is fast so that it doesn't block the end of the build if a command produces huge quantities of output. It's hard to say if this will be a real issue without some testing
We're re-parsing information which we're already getting from the compiler in structured form. I see the appeal of not reporting a diagnostic twice if multiple compile jobs report it though

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

jakepetroules · 2025-11-20T23:46:02Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+
+    /// Split compiler output into individual diagnostic segments
+    /// Format: /path/to/file.swift:line:column: severity: message
+    private func splitIntoDiagnostics(_ output: String) -> [ParsedDiagnostic] {


I don't think we should be doing any output parsing at this level, Swift Build already has an entire subsystem dedicated to doing this.

@jakepetroules I would agree, however the events we're receiving from SwiftBuild accumulates every diagnostic message into a singular data buffer -- when emitting this as-is, it's possible that we'd be coupling some info-level diagnostics with error-level diagnostics with no way to separate the severity. Splitting the string on a per-diagnostic basis is the only way to achieve this in this way.

The observability scope that we use to emit these diagnostics will capture the entire string blob, and we have to decide with what severity to emit the entire message. I'm not sure if there's an alternative path here that would give us the same ergonomics on the user front, but IMO it's preferred to separate each diagnostic and ensure that we're emitting them with the appropriate severity, rather than sending the entire string of possibly many diagnostics with varying severities.

Let me try to clarify: Swift Build already parses the individual diagnostic messages into structured data objects independently of the singular output buffer, which is for the textual output of the tool. So Swift Build is already doing the equivalent of what splitIntoDiagnostics is doing, and those messages are given to you in the diagnostics message. They include rich information including severity, line number, and so on.

Similar to what I mentioned elsewhere about the taskStarted/taskEnded events, you want to capture those diagnostics' association to the specific task (e.g. unprocessedDiagnostics should be a dictionary rather than an array, and belongs in BuildState rather than in the top level object), and then replay them at task completion time, without attempting to do your own parsing.

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

jakepetroules · 2025-11-21T04:41:23Z

2. We're re-parsing information which we're already getting from the compiler in structured form. I see the appeal of not reporting a diagnostic twice if multiple compile jobs report it though

I also pointed this out inline, though I'm not sure why the re-parsing relates to deduplication? We should be able to deduplicate diagnostics whether we parse them again or use the existing ones.

bripeticca · 2025-11-21T16:40:20Z

though I'm not sure why the re-parsing relates to deduplication

(@jakepetroules @owenv -- tagging for visibility, GitHub notifications can be weird)

Re-parsing doesn't affect the de-duplication -- when tracking the data buffer per task, I also track whether we've emitted the associated output for a given task (using its signature) and guard against this before emitting for that task again. We only go down this path (emitting for a given task) once we've received the task completed event.

I mentioned this inline as well but for visibility: the re-parsing just addresses the fact that for a given task signature, we have an accumulated data buffer that contains all possible diagnostic messages coming from the compiler. I find that the user ergonomics aren't great when simply emitting the entire string blob through the observability scope, since these diagnostics can have varying severities and we'll have to decide up-front which severity to choose to emit the entire string of all diagnostics.

I do also maintain a list of the DiagnosticInfo that we omit in favour of emitting the OutputInfo containing the same diagnostic messages, but with the plus of having the pre-formatted code snippet (the DiagnosticInfo is missing the pre-formatted code snippet but contains enough information to recreate it ourselves, and it was suggested that we instead fall back to using the OutputInfo for that reason).

Perhaps some more discussion is needed here. 😄

* Remove taskStarted outputStream emissions * Propagate exception if unable to find path

bripeticca · 2025-11-21T21:03:03Z

@swift-ci please test

bripeticca · 2025-11-21T21:04:34Z

@swift-ci please test windows

The TaskDataBuffer introduces some extra complexity in its handling of various buffers we'd actually like to track and emit, rather than ignore. We will keep multiple buffers depending on the information we have available i.e. whether there's an existing task signature buffer, taskID buffer, targetID buffer, or simply a global buffer.

If there is no command line display strings available for a failed task, we should demote this message to info-level to avoid cluttering the output stream with messages that may not be incredibly helpful. To consider here: if this is the only error, we should be able to expose this as an error and perhaps omit "<no command line>".

bripeticca · 2025-12-02T17:17:38Z

@swift-ci please test

owenv · 2025-12-02T22:39:53Z

The failing tests seem to be command plugins that do things like this

// Check if the build log contains "-enable-testing" flag
        let isTestable = result.logText.contains("-enable-testing")
        if isTestable != shouldTestable {
            fatalError("Testability mismatch: expected \(shouldTestable), but got \(isTestable):\n\(result.logText)")
        }

Not sure if we're failing to print the command line in the log, or the observabilityscope isn't adding it to logText

owenv · 2025-12-02T22:46:26Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+            private var taskSignatureBuffer: [String: Data] = [:]
+            private var taskIDBuffer: [Int: Data] = [:]
+            private var targetIDBuffer: [Int: Data] = [:]
+            private var globalBuffer: Data = Data()


It doesn't look like we currently print this anywhere. Emitting it at the end of the build might work to start, but we might also consider printing up to each newline we see since some "build preparation" messages get emitted w/ no task and target

I realized that while we emit global diagnostics fairly often, the build system doesn't emit a lot of global raw output, so this may actually be ok as-is for now. I'm going to look at the build system to see if we can make changes to guarantee that raw output is always attached to a task

After our conversation earlier I checked this as well and the BuildOperationConsoleOutputEmitted constructors for non-task output are never called (outside of a test). The only possible way output could be non-task-associated at all is through its Decodable initializer, and the sole place that's called is in the IPC decoding over the wire, so no chance because no such objects are constructed in the first place.

I think we should change the API to guarantee this, as global or target-attached console output doesn't make any sense anyways.

For now @bripeticca can just ignore it (meaning, let's eliminate the field from this PR).

owenv · 2025-12-02T22:46:58Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+            if buildSystem.enableTaskBacktraces {
+                buildState.collectedBacktraceFrames.add(frame: info)
+            }
+        case .planningOperationStarted, .planningOperationCompleted, .reportBuildDescription, .reportPathMap, .preparedForIndex, .buildStarted, .preparationComplete, .targetUpToDate, .targetComplete, .taskUpToDate:


Should we emit any buffered target messages upon receiving targetComplete here?

Same comment as #9362 (comment), this may be ok as-is

Yup, not used.

It would be good to remove targets from the in-progress map when hitting targetComplete though.

jakepetroules · 2025-12-03T10:48:12Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+        }
+
+        mutating func appendToBuffer(_ info: SwiftBuildMessage.OutputInfo) {
+            // Attempt to key by taskSignature; at times this may not be possible,


The reason this taskID vs taskSignature situation exists was because we started to transition from IDs (which change on every build operation) to signatures (which are stable across build operations), but didn't complete it, and also ran into performance issues (106579386) and turned them off for console output at least... I don't remember why and maybe we can re-enable them at some point, but we should definitely clean this up (not that it should block this PR though).

Thanks for the clarification!

jakepetroules · 2025-12-03T10:54:31Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+            try buildState.started(task: info)
+
+            if let commandLineDisplay = info.commandLineDisplayString {
+                self.observabilityScope.emit(info: "\(info.executionDescription)\n\(commandLineDisplay)")


These log emissions still need to be deferred to the task complete event, like the diagnostics and output.

jakepetroules · 2025-12-03T10:56:21Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+    private var buildState: BuildState = .init()
+
+    let progressAnimation: ProgressAnimationProtocol
+    var serializedDiagnosticPathsByTargetName: [String: [Basics.AbsolutePath]] = [:]


This needs to be keyed by targetID, not target name. Target names are not globally unique.

jakepetroules · 2025-12-03T10:59:01Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+            if buildSystem.enableTaskBacktraces {
+                buildState.collectedBacktraceFrames.add(frame: info)
+            }
+        case .planningOperationStarted, .planningOperationCompleted, .reportBuildDescription, .reportPathMap, .preparedForIndex, .buildStarted, .preparationComplete, .targetUpToDate, .targetComplete, .taskUpToDate:


It would be good to remove targets from the in-progress map when hitting targetComplete though.

jakepetroules · 2025-12-03T11:01:19Z

Sources/Basics/Observability.swift

 public protocol DiagnosticsHandler: Sendable {
    func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic)
+
+    func printToOutput(message: String)


Call this func print(_ output: String, verbose: Bool) instead? Since we already have a viable implementation.

I don't think it's the DiagnosticHandlers responsibility to print the diagnostic here. We should instead have a "LoggingHandler" which would know where to emit the "message", whether it's to stdout, stderr, to a file, or some other place.

jakepetroules · 2025-12-03T11:04:45Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+            if info.appendToOutputStream {
+                emitInfoAsDiagnostic(info: info)
+            } else {
+                unprocessedDiagnostics.append(info)


I think we don't need to save these at all. By definition these are the diagnostics which were parsed from the textual output and therefore the textual output will contain them.

jakepetroules · 2025-12-03T11:07:57Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+            buildSystem.delegate?.buildSystem(buildSystem, didUpdateTaskProgress: message)
+        case .diagnostic(let info):
+            if info.appendToOutputStream {
+                emitInfoAsDiagnostic(info: info)


We need to capture task-level diagnostics and defer emission of those until the taskCompleted event.

Global diagnostics and target diagnostics can be emitted immediately.

bkhouri

This is great work, but we should also include automated tests as part of this change to ensure we won't regress the behaviour.

bkhouri · 2025-12-03T14:07:25Z

Sources/Basics/Observability.swift

 public protocol DiagnosticsHandler: Sendable {
    func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic)
+
+    func printToOutput(message: String)


issue: the function name is a bit misleading. Where if the output going to? to a file, stdout, stderr, somewhere else? can we please update the function name to make this more explicit?

This function is meant to be a temporary workaround given that we are emitting diagnostics from the compiler output accumulated as one string blob, and observability scope usually demands a severity along with this despite the fact that these diagnostics could very possibly have differing severities.

It's a little hacky but I'm hoping that future discussion surrounding how we'd like to architect logging will improve this :)

bkhouri · 2025-12-03T14:09:38Z

Sources/Basics/Observability.swift

 public protocol DiagnosticsHandler: Sendable {
    func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic)
+
+    func printToOutput(message: String)


I don't think it's the DiagnosticHandlers responsibility to print the diagnostic here. We should instead have a "LoggingHandler" which would know where to emit the "message", whether it's to stdout, stderr, to a file, or some other place.

bkhouri · 2025-12-03T14:11:06Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

 }

+/// Convenience extensions to extract taskID and targetID from the LocationContext.
+extension SwiftBuildMessage.LocationContext {


question: Should these extension belong in SwiftBuild?

bkhouri · 2025-12-03T14:12:07Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+    }
+}
+
+/// Handler for SwiftBuildMessage events sent by the SWBBuildOperation.


suggestion: can we move this class to it's own source file?

bkhouri · 2025-12-03T14:16:43Z

Sources/SwiftBuildSupport/SwiftBuildSystem.swift

+    /// Tracks the task IDs for failed tasks.
+    private var failedTasks: [Int] = []
+    /// Tracks the tasks by their signature for which we have already emitted output.
+    private var tasksEmitted: Set<String> = []


question (possibly-blocking): what is the difference between tasksEmitted and taskIDsEmitted? If they are tracking the same thing, can we remove one? If we need both, could you please provide an explanation?

bripeticca added 2 commits November 11, 2025 12:07

owenv reviewed Nov 12, 2025

View reviewed changes

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

bripeticca added 5 commits November 13, 2025 13:33

Implement per-task-buffer of Data output

b1ff231

Fallback to locationContext if locationContext2 properties are nil

ac6b81b

Merge branch 'main' into swb/diagnosticcodesnippet

1ae0f38

Cleanup; add descriptions related to redundant task output

b81bfca

attempt to parse decoded string into individual diagnostics

f3aaabf

bripeticca force-pushed the swb/diagnosticcodesnippet branch from a20f020 to f3aaabf Compare November 20, 2025 18:56

cleanup

c48e606

bripeticca force-pushed the swb/diagnosticcodesnippet branch from 1dcaaeb to c48e606 Compare November 20, 2025 18:58

bripeticca changed the title ~~[WIP] Capture code snippet from diagnostic compiler output~~ Capture code snippet from diagnostic compiler output Nov 20, 2025

bripeticca marked this pull request as ready for review November 20, 2025 19:21

bripeticca requested review from bkhouri, cmcgee1024, daveyc123, dschaefer2, jakepetroules, plemarquand and rconnell9 as code owners November 20, 2025 19:21

owenv reviewed Nov 20, 2025

View reviewed changes

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

jakepetroules reviewed Nov 20, 2025

View reviewed changes

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

jakepetroules reviewed Nov 20, 2025

View reviewed changes

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

jakepetroules reviewed Nov 21, 2025

View reviewed changes

Sources/SwiftBuildSupport/SwiftBuildSystem.swift Outdated Show resolved Hide resolved

bripeticca added 2 commits November 21, 2025 15:38

Revert diagnostic parsing and emit directly to outputStream

f14600c

Address PR comments

359331a

* Remove taskStarted outputStream emissions * Propagate exception if unable to find path

bripeticca added 6 commits November 24, 2025 16:21

implement generic print method for observability scope

56f0a45

minor changes to TaskDataBuffer + cleanup

08306e2

cleanup; stronger assertions for redundant task output

4074c59

Fix protocol adherence errors

05ee043

rconnell9 approved these changes Dec 2, 2025

View reviewed changes

owenv reviewed Dec 2, 2025

View reviewed changes

jakepetroules reviewed Dec 3, 2025

View reviewed changes

jakepetroules requested changes Dec 3, 2025

View reviewed changes

bkhouri requested changes Dec 3, 2025

View reviewed changes

Capture code snippet from diagnostic compiler output #9362

Are you sure you want to change the base?

Capture code snippet from diagnostic compiler output #9362

Uh oh!

Conversation

bripeticca commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Uh oh!

Uh oh!

bripeticca commented Nov 20, 2025

Uh oh!

owenv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bripeticca Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakepetroules Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jakepetroules commented Nov 21, 2025

Uh oh!

bripeticca commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bripeticca commented Nov 21, 2025

Uh oh!

bripeticca commented Nov 21, 2025

Uh oh!

bripeticca commented Dec 2, 2025

Uh oh!

owenv commented Dec 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakepetroules Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bkhouri left a comment

Choose a reason for hiding this comment

bripeticca commented Nov 11, 2025 •

edited

Loading

bripeticca Nov 21, 2025 •

edited

Loading

jakepetroules Nov 21, 2025 •

edited

Loading

bripeticca commented Nov 21, 2025 •

edited

Loading

jakepetroules Dec 3, 2025 •

edited

Loading