docs: document Xcode 26.4 attachment and BuildOperationMetrics changes

Update Xcactivitylog Format doc with SLF version history table,
IDEActivityLogSectionAttachment section, and BuildOperationMetrics
format change in Xcode 26.4.

Update JSON Format doc with Attachments section covering
BuildOperationTaskMetrics, BuildOperationMetrics (both old and
Xcode 26.4+ formats), and BuildOperationTaskBacktrace.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: giginet

docs/JSON Format.md

@@ -76,6 +76,87 @@ Other fields:
 - `compilationEndTimestamp`: Timestamp in which the actual compilation finished. For a Target this could be before `endTimestamp` because in the new Xcode Build System linking can happen way after compilation.
 - `compilationDuration` Actual duration in seconds of just the compilation phase. In a Target this could be significant shorter than the `duration`.
 
+## Attachments (Xcode 15.3+)
+
+When using the `dump` command, each `IDEActivityLogSection` may include an `attachments` array. This was introduced in SLF version 11 (Xcode 15.3). Each attachment has an `identifier`, `majorVersion`, `minorVersion`, and one of the following typed payloads:
+
+### BuildOperationTaskMetrics
+
+Per-task execution metrics:
+
+```json
+{
+  "identifier": "com.apple.dt.ActivityLogSectionAttachment.TaskMetrics",
+  "majorVersion": 1,
+  "minorVersion": 0,
+  "metrics": {
+    "utime": 1834,
+    "stime": 1723,
+    "maxRSS": 3391488,
+    "wcStartTime": 793866997013418,
+    "wcDuration": 141479
+  }
+}
+```
+
+### BuildOperationMetrics
+
+Aggregate build operation metrics. The JSON format differs by Xcode version:
+
+**Xcode 15.3 - Xcode 16.x:**
+```json
+{
+  "identifier": "com.apple.dt.ActivityLogSectionAttachment.BuildOperationMetrics",
+  "majorVersion": 1,
+  "minorVersion": 0,
+  "buildOperationMetrics": {
+    "clangCacheHits": 0,
+    "clangCacheMisses": 2,
+    "swiftCacheHits": 0,
+    "swiftCacheMisses": 8
+  }
+}
+```
+
+**Xcode 26.4+:**
+```json
+{
+  "identifier": "com.apple.dt.ActivityLogSectionAttachment.BuildOperationMetrics",
+  "majorVersion": 1,
+  "minorVersion": 0,
+  "buildOperationMetrics": {
+    "counters": {},
+    "taskCounters": {
+      "SwiftDriver": {
+        "moduleDependenciesNotValidatedTasks": 1
+      }
+    }
+  }
+}
+```
+
+All fields in `buildOperationMetrics` are optional to support both formats.
+
+### BuildOperationTaskBacktrace
+
+Backtrace frames explaining why a build task was executed:
+
+```json
+{
+  "identifier": "com.apple.dt.ActivityLogSectionAttachment.TaskBacktrace",
+  "majorVersion": 1,
+  "minorVersion": 0,
+  "backtrace": [
+    {
+      "description": "'Planning Swift module Foo' had never run",
+      "category": { "ruleNeverBuilt": {} }
+    }
+  ]
+}
+```
+
+## Detail step types
+
 When possible, the `signature` content of `detail` steps is parsed to determine its type. This makes it easier to aggregate the data.
 
 Value | Description

docs/Xcactivitylog Format.md

@@ -136,7 +136,15 @@ You can get these tokens:
 [type: "string", value: "Prepare build"],
 ```
 
-The first integer is the version of the `SLF` format used. In Xcode 10.x and 11 Beta, the version is 10. The values after the version are the actual content of the log.
+The first integer is the version of the `SLF` format used. The values after the version are the actual content of the log.
+
+### SLF version history
+
+Version | Xcode Version | Changes
+--- | --- | ---
+10 | Xcode 10.x - 14.x | Initial format
+11 | Xcode 15.3+ | Added `IDEFoundation.IDEActivityLogSectionAttachment` list to `IDEActivityLogSection`
+12 | Xcode 26.2+ | Added an unknown integer field before `subtitle` in `IDEActivityLogSection`
 
 ## Parsing an xcactivitylog
 
@@ -156,3 +164,29 @@ Inside the logs you can find these classes:
 If you search for them, you will find that they belong to the IDEFoundation.framework. A private framework part of Xcode. You can class dump it to get the headers of those classes. Once you have the headers, you will have the name and type of the properties that belong to the class. Now, you can match them to the tokens you got from the log. Some of them are in the same order than in the headers, but for others it will be about trial and error.
 
 In the project you can find those classes with their properties in the order in which they appear in the log in the file [IDEActivityModel.swift](../Sources/XCLogParser/activityparser/IDEActivityModel.swift).
+
+## IDEActivityLogSectionAttachment (SLF version 11+)
+
+Starting with SLF version 11 (Xcode 15.3), each `IDEActivityLogSection` includes an array of `IDEFoundation.IDEActivityLogSectionAttachment` entries after the `xcbuildSignature` field. Each attachment has an `identifier` string, a `majorVersion` integer, a `minorVersion` integer, and a JSON payload. The identifier determines the type of the JSON payload:
+
+Identifier | JSON Type | Description
+--- | --- | ---
+`...TaskMetrics` | `BuildOperationTaskMetrics` | Per-task timing metrics (`utime`, `stime`, `maxRSS`, `wcStartTime`, `wcDuration`)
+`...TaskBacktrace` | `BuildOperationTaskBacktrace` | Backtrace frames explaining why a task was run
+`...BuildOperationMetrics` | `BuildOperationMetrics` | Aggregate build operation metrics (see below)
+
+### BuildOperationMetrics format changes
+
+In **Xcode 15.3 - Xcode 16.x**, the `BuildOperationMetrics` JSON contains compiler cache statistics:
+
+```json
+{"clangCacheHits":0,"clangCacheMisses":2,"swiftCacheHits":0,"swiftCacheMisses":8}
+```
+
+Starting with **Xcode 26.4**, the format changed to a dynamic counter-based structure:
+
+```json
+{"counters":{},"taskCounters":{"SwiftDriver":{"moduleDependenciesNotValidatedTasks":1}}}
+```
+
+XCLogParser supports both formats. All fields are optional to maintain backward compatibility.