From 24f6ada45076756d00adab114b2c35663016980a Mon Sep 17 00:00:00 2001 From: Thorsten Fuchs <76904008+ThorFuchs@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:49:55 +0100 Subject: [PATCH] Add JSONPatch.difference producing RFC 6902 operations JSONPatch.difference(from:to:options:) and differenceWithReport compute a deterministic structural patch that turns one exact value into another. Equal values produce no operation; objects diff by exact key, arrays keep their equal prefix and suffix and compare the remaining elements by position, and other changes are replaced. No move, copy or test is generated, and the result is not minimal. Both inputs, every comparison, Pointer and produced operation share one cumulative patch ledger with cancellation checks. Tests cover expected operations, Pointer escaping, scalar-distinct keys, root replacement, a 600-pair generated corpus where applying the patch yields the target, limits, reports and cancellation. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 8 + Documentation/Architecture/Patch.md | 20 +++ .../Qualification/TestDiscovery.json | 6 +- Sources/JSONCLIEngine/CLIBuildIdentity.swift | 2 +- .../JSONPatch/Documentation.docc/JSONPatch.md | 10 ++ Sources/JSONPatch/JSONPatchDifference.swift | 143 ++++++++++++++++++ Tests/JSONPatchTests/DifferenceTests.swift | 133 ++++++++++++++++ 7 files changed, 318 insertions(+), 4 deletions(-) create mode 100644 Sources/JSONPatch/JSONPatchDifference.swift create mode 100644 Tests/JSONPatchTests/DifferenceTests.swift diff --git a/CHANGELOG.md b/CHANGELOG.md index 82b53ef..84238b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,14 @@ Tests cover the RFC's Appendix B number vectors, its sample document and its key-sorting example. The writer does not hash or sign. The existing writer and its scalar key order are unchanged. +- Add `JSONPatch.difference(from:to:options:)` and `differenceWithReport`, which + compute RFC 6902 operations that turn one exact value into another. Equal values + (exact decimals, scalar keys, order-independent objects) produce no operation; + objects diff by key, arrays keep their equal prefix and suffix and compare the + rest by position, other changes are replaced. The result is deterministic and + applies to the source to give the target, but is not minimal and never uses + `move`, `copy` or `test`. One cumulative patch ledger covers both inputs and + the produced operations. ## Unreleased — 1.9.1 hygiene diff --git a/Documentation/Architecture/Patch.md b/Documentation/Architecture/Patch.md index 1ed906b..63e1fb3 100644 --- a/Documentation/Architecture/Patch.md +++ b/Documentation/Architecture/Patch.md @@ -24,6 +24,26 @@ Reject negative index construction, invalid escape syntax and configured token/b Pointer construction is a convenience over strict tokens. It adds no wildcards, JSONPath, jq expressions, automatic parent creation or ambiguous autovivification. Test empty keys, slash/tilde, Unicode scalar identity, numeric object keys, percent fragments and repeated resolution with one immutable Pointer. +## Structural difference + +`JSONPatch.difference(from:to:options:)` (1.10) produces RFC 6902 operations that +turn a source value into a target value, under one cumulative `.patch` ledger +that admits both inputs, charges every comparison, Pointer and operation, and +checks cancellation in its loop. The result is deterministic and always applies +to the source to give a value equal to the target; it is not a minimal edit script. + +- Equality is the exact model's: equal decimals (`1.0` and `1`), decoded scalar + keys and order-independent objects produce no operation. Canonically + equivalent but scalar-distinct keys are different members. +- Objects: members only in the source are removed (source order), members only in + the target are added (target order), and shared members are compared recursively. +- Arrays: the longest equal prefix and suffix are kept; the remaining elements + are compared by position, surplus source elements are removed from the highest + index down, and surplus target elements are added in order. +- Different kinds and unequal scalars are replaced; a root change uses the empty Pointer. +- No `move`, `copy` or `test` operation is generated. An insertion at the front of + a long array therefore produces one operation per shifted element. + ## JSON Merge Patch JSONMergePatch implements RFC 7396 in the JSONPatch product. This offers an object-shaped partial-update use case beside RFC 6902 operations. The new type uses the exact JSON model and an explicitly bounded staged application. diff --git a/Documentation/Qualification/TestDiscovery.json b/Documentation/Qualification/TestDiscovery.json index b6edb38..e7aa7e0 100644 --- a/Documentation/Qualification/TestDiscovery.json +++ b/Documentation/Qualification/TestDiscovery.json @@ -5,7 +5,7 @@ "JSONSchemaTests": 79, "JSONRegexRuntimeTests": 16, "JSONStreamingTests": 36, - "JSONPatchTests": 16, + "JSONPatchTests": 22, "JSONIntegrationTests": 45, "JSONHTMLTests": 97, "JSONBridgesTests": 10, @@ -77,7 +77,7 @@ "JSONSchemaTests": 79, "JSONRegexRuntimeTests": 16, "JSONStreamingTests": 36, - "JSONPatchTests": 16, + "JSONPatchTests": 22, "JSONIntegrationTests": 45, "JSONHTMLTests": 81, "JSONBridgesTests": 10, @@ -93,7 +93,7 @@ "JSONSchemaTests": 79, "JSONRegexRuntimeTests": 16, "JSONStreamingTests": 36, - "JSONPatchTests": 16, + "JSONPatchTests": 22, "JSONIntegrationTests": 45, "JSONHTMLTests": 81, "JSONBridgesTests": 10, diff --git a/Sources/JSONCLIEngine/CLIBuildIdentity.swift b/Sources/JSONCLIEngine/CLIBuildIdentity.swift index 2c12cef..136f916 100644 --- a/Sources/JSONCLIEngine/CLIBuildIdentity.swift +++ b/Sources/JSONCLIEngine/CLIBuildIdentity.swift @@ -2,6 +2,6 @@ // Generated by Scripts/generate_cli_identity.py; excludes this file. // SHA-256 of the ordered Package.swift + Sources content manifest (DocC catalogs excluded), not a Git commit. package enum CLIBuildIdentity { - package static let revision = "sha256:528b7f15a54f6c25125196ffef9ec2979a2b05c549f214ac8c643503e0becc48" + package static let revision = "sha256:ab828e1c70d46c10f7a6431f5e9ef22ac469b8609778e3e99b7a0f6af77891ff" package static let kind = "source-sha256" } diff --git a/Sources/JSONPatch/Documentation.docc/JSONPatch.md b/Sources/JSONPatch/Documentation.docc/JSONPatch.md index 999ad30..32f1391 100644 --- a/Sources/JSONPatch/Documentation.docc/JSONPatch.md +++ b/Sources/JSONPatch/Documentation.docc/JSONPatch.md @@ -14,6 +14,14 @@ no partially changed document and leaves the caller value unchanged. ``JSONPatchResult`` distinguishes a removed root from a document containing JSON null. A subsequent root add can recreate a removed document. +``JSONPatch/difference(from:to:options:)`` computes a patch that turns one value +into another. It is structural and deterministic, not minimal: equal values +(by exact decimal, scalar and order-independent object equality) produce no +operation, object members are removed, added or compared by exact key, arrays +keep their equal prefix and suffix and compare the rest by position, and other +changes are replaced. It never emits `move`, `copy` or `test`, and applying the +result to the source always yields a value equal to the target. + ``JSONMergePatch`` implements RFC 7396: null object members remove properties, object patches recurse with explicit frames, and other values replace the selected value. A root null replaces the document with JSON null. Arrays are @@ -33,6 +41,8 @@ earlier oversized stage. Reports expose logical accounting, not process RSS. ### JSON Patch - ``JSONPatch`` +- ``JSONPatch/difference(from:to:options:)`` +- ``JSONPatch/differenceWithReport(from:to:options:)`` - ``JSONPatchOperation`` - ``JSONPatchResult`` - ``JSONPatchOptions`` diff --git a/Sources/JSONPatch/JSONPatchDifference.swift b/Sources/JSONPatch/JSONPatchDifference.swift new file mode 100644 index 0000000..680bf85 --- /dev/null +++ b/Sources/JSONPatch/JSONPatchDifference.swift @@ -0,0 +1,143 @@ +// SPDX-License-Identifier: Apache-2.0 +// Original implementation of a bounded structural difference producing RFC 6902 operations. +import JSON + +extension JSONPatch { + package init(admitted operations: [JSONPatchOperation]) { self.operations = operations } + + /// Computes a patch that turns `source` into `target` when applied to `source`. + /// + /// The difference is structural and deterministic, not a minimal edit script: + /// + /// - Equal values, using the exact model's equality (decimal value, decoded + /// scalars, order-independent objects), produce no operation. `1.0` and `1` + /// are equal, so neither is replaced by the other. + /// - Object members are compared by exact key. Members only in `source` are + /// removed, members only in `target` are added in `target` order, and shared + /// members are compared recursively. A changed member order alone produces no + /// operation, because object equality ignores order. + /// - Arrays keep their longest equal prefix and suffix. The remaining elements + /// are compared pairwise by position; surplus `source` elements are removed + /// from the highest index down, and surplus `target` elements are added in order. + /// Elements are never moved or copied, so an inserted element at the front + /// of a long array can produce many operations. + /// - Values of different kinds, and unequal scalars, are replaced. A root + /// change replaces the root through the empty Pointer. + /// + /// The result contains no `test`, `move` or `copy` operations. + /// + /// - Returns: A patch whose application to `source` yields a value equal to `target`. + /// - Throws: Resource failure for oversized inputs, operation counts or Pointer + /// lengths, or cancellation. + /// + /// - Parameters: + /// - source: The value the patch will be applied to. + /// - target: The value the patch must produce. + /// - options: Finite limits for admission, comparison and the produced operations. + public static func difference(from source: JSON, to target: JSON, options: JSONPatchOptions = .init()) throws -> JSONPatch { + try differenceWithReport(from: source, to: target, options: options).result + } + /// Computes the structural difference with cumulative work accounting. + /// + /// See ``difference(from:to:options:)`` for the semantics. + /// + /// - Returns: The patch and the charged counts of the single invocation ledger. + /// - Throws: Resource failure for oversized inputs, operation counts or Pointer + /// lengths, or cancellation. + /// + /// - Parameters: + /// - source: The value the patch will be applied to. + /// - target: The value the patch must produce. + /// - options: Finite limits for admission, comparison and the produced operations. + public static func differenceWithReport(from source: JSON, to target: JSON, options: JSONPatchOptions = .init()) throws -> JSONOperationReport { + var meter = try JSONWorkMeter(limits: options.limits, domain: .patch) + let patch = try difference(from: source, to: target, meter: &meter) + return .init(result: patch, statistics: meter.statistics()) + } + package static func difference(from source: JSON, to target: JSON, meter: inout JSONWorkMeter) throws -> JSONPatch { + try JSONAdmission.value(source, meter: &meter) + try meter.resetValueBounds(); try JSONAdmission.value(target, meter: &meter) + enum Step { + /// Compare two values found at the same path. + case compare(path: [JSONKey], source: JSON, target: JSON) + /// Emit an operation after the steps pushed before it have run. + case emit(JSONPatchOperation) + } + var operations: [JSONPatchOperation] = [] + var stack: [Step] = [] + func push(_ step: Step, meter: inout JSONWorkMeter) throws { + try meter.work(); try meter.retain(JSONLogicalWeights.frame); stack.append(step) + } + func pointer(_ path: [JSONKey], meter: inout JSONWorkMeter) throws -> JSONPointer { + try JSONPointer.decodedTokens(path, meter: &meter) + } + func extended(_ path: [JSONKey], _ key: JSONKey, meter: inout JSONWorkMeter) throws -> [JSONKey] { + try meter.require(.pointerTokens, UInt64(path.count) + 1) + for _ in path { try meter.work() } + try meter.retain(16); return path + [key] + } + func index(_ value: Int, meter: inout JSONWorkMeter) throws -> JSONKey { + try JSONKey(String(value), meter: &meter) + } + try push(.compare(path: [], source: source, target: target), meter: &meter) + while let step = stack.popLast() { + try meter.release(JSONLogicalWeights.frame); try meter.work() + switch step { + case .emit(let operation): + try meter.require(.operations, UInt64(operations.count) + 1) + try meter.retain(JSONLogicalWeights.frame); operations.append(operation) + case .compare(let path, .object(let a), .object(let b)): + // Steps are pushed in reverse so they run in source/target order. + var pending: [Step] = [] + for member in a { + try meter.work() + if try b.lookup(member.key.string, meter: &meter) == nil { + pending.append(.emit(.remove(path: try pointer(extended(path, member.key, meter: &meter), meter: &meter)))) + } + } + for member in b { + try meter.work() + let childPath = try extended(path, member.key, meter: &meter) + if let existing = try a.lookup(member.key.string, meter: &meter) { + pending.append(.compare(path: childPath, source: existing, target: member.value)) + } else { + pending.append(.emit(.add(path: try pointer(childPath, meter: &meter), value: member.value))) + } + } + for item in pending.reversed() { try push(item, meter: &meter) } + case .compare(let path, .array(let a), .array(let b)): + let shared = min(a.count, b.count) + var prefix = 0 + while prefix < shared, try JSONComparison.equals(a[prefix], b[prefix], meter: &meter) { prefix += 1 } + var suffix = 0 + while suffix < shared - prefix, + try JSONComparison.equals(a[a.count - 1 - suffix], b[b.count - 1 - suffix], meter: &meter) { suffix += 1 } + let middleA = a.count - prefix - suffix, middleB = b.count - prefix - suffix + let paired = min(middleA, middleB) + var pending: [Step] = [] + for offset in 0.. JSON { try JSONParser().parse(text) } + +/// Applies the difference and returns the operations, recording any mismatch. +@discardableResult +private func roundTrip(_ source: JSON, _ target: JSON, sourceLocation: SourceLocation = #_sourceLocation) throws -> [JSONPatchOperation] { + let patch = try JSONPatch.difference(from: source, to: target) + let result = try patch.applying(to: source) + #expect(result == .document(target), sourceLocation: sourceLocation) + return patch.operations +} + +@Test func differenceOfEqualValuesIsEmpty() throws { + for text in ["null", "true", "0", "\"é\"", "[]", "{}", #"{"a":[1,{"b":null}],"c":"x"}"#] { + #expect(try roundTrip(parse(text), parse(text)).isEmpty) + } + // Exact equality: equal decimals and a different member order are not changes. + #expect(try roundTrip(parse(#"{"n":1.0,"m":[2e1],"a":1,"b":2}"#), parse(#"{"b":2,"a":1,"n":1,"m":[20]}"#)).isEmpty) +} + +@Test func differenceProducesExpectedObjectOperations() throws { + let source = try parse(#"{"keep":1,"drop":2,"change":{"x":1,"y":[1,2]},"kind":[1]}"#) + let target = try parse(#"{"keep":1,"change":{"x":2,"y":[1,2]},"kind":{"a":1},"new":null}"#) + let operations = try roundTrip(source, target) + #expect(operations == [ + .remove(path: try JSONPointer(parsing: "/drop")), + .replace(path: try JSONPointer(parsing: "/change/x"), value: 2), + .replace(path: try JSONPointer(parsing: "/kind"), value: try parse(#"{"a":1}"#)), + .add(path: try JSONPointer(parsing: "/new"), value: .null), + ]) +} + +@Test func differenceKeepsArrayPrefixAndSuffix() throws { + // Insertion in the middle: prefix [1,2] and suffix [9] stay, one add. + #expect(try roundTrip(parse("[1,2,9]"), parse("[1,2,3,9]")) == [.add(path: try JSONPointer(parsing: "/2"), value: 3)]) + // Removal in the middle. + #expect(try roundTrip(parse("[1,2,3,9]"), parse("[1,2,9]")) == [.remove(path: try JSONPointer(parsing: "/2"))]) + // Several removals run from the highest index down. + #expect(try roundTrip(parse("[0,1,2,3,4]"), parse("[0,4]")) == [ + .remove(path: try JSONPointer(parsing: "/3")), .remove(path: try JSONPointer(parsing: "/2")), + .remove(path: try JSONPointer(parsing: "/1")), + ]) + // A changed element in place is compared recursively. + #expect(try roundTrip(parse(#"[{"a":1},{"a":2}]"#), parse(#"[{"a":1},{"a":3}]"#)) == + [.replace(path: try JSONPointer(parsing: "/1/a"), value: 3)]) + // Pairwise comparison, then surplus adds; no moves are produced. + try roundTrip(parse("[1,2,3]"), parse("[3,2,1,0]")) + try roundTrip(parse("[[1],[2]]"), parse("[[2],[1],[]]")) + try roundTrip(parse("[1,1,1]"), parse("[1,1]")) + try roundTrip(parse("[]"), parse("[1,[2],{}]")) + try roundTrip(parse("[1,[2],{}]"), parse("[]")) +} + +@Test func differenceEscapesKeysAndHandlesRootAndUnicode() throws { + let source = try parse(#"{"a/b":1,"m~n":2,"":3,"é":4}"#) + let target = try parse(#"{"a/b":5,"m~n":2,"":6,"é":4}"#) + let operations = try roundTrip(source, target) + #expect(operations.map(\.path.string) == ["/é", "/a~1b", "/", "/e\u{301}"]) + // Decoded scalars are distinct keys, even when canonically equivalent. + #expect(operations.first == .remove(path: try JSONPointer(tokens: ["é"]))) + // Root kind changes replace the root through the empty Pointer. + #expect(try roundTrip(parse("[1]"), parse(#"{"a":1}"#)) == [.replace(path: try JSONPointer(parsing: ""), value: try parse(#"{"a":1}"#))]) + #expect(try roundTrip(parse("1"), parse("null")) == [.replace(path: try JSONPointer(parsing: ""), value: .null)]) + #expect(try roundTrip(parse("\"é\""), parse("\"e\u{301}\"")).count == 1) +} + +/// A deterministic generator over small nested values, so the property runs on a fixed corpus. +private struct Generator { + var state: UInt64 + mutating func next(_ bound: Int) -> Int { + state = state &* 6364136223846793005 &+ 1442695040888963407 + return Int((state >> 33) % UInt64(bound)) + } + mutating func value(depth: Int) throws -> JSON { + switch next(depth > 2 ? 4 : 6) { + case 0: return .null + case 1: return .boolean(next(2) == 0) + case 2: return .number(try JSONNumber(parsing: ["0", "1", "1.0", "-2", "3e2", "0.5"][next(6)])) + case 3: return .string(["", "a", "b", "é", "a/b", "~"][next(6)]) + case 4: return .array(try (0.. 500) +} + +@Test func differenceIsBoundedReportedAndCancellable() async throws { + let source = try parse(#"{"a":[1,2,3],"b":{"c":"x"}}"#), target = try parse(#"{"a":[1,3],"b":{"c":"y"},"d":true}"#) + let report = try JSONPatch.differenceWithReport(from: source, to: target) + #expect(report.result.operations.count == 3) + #expect(report.statistics.domain == .patch) + #expect(report.statistics[.workUnits] > 0) + var limits = JSONLimits.balanced; limits[.operations] = 2 + do { _ = try JSONPatch.difference(from: source, to: target, options: .init(limits: limits)); Issue.record("Expected an operation limit failure") } + catch let failure as JSONFailure { #expect(failure.code == .limitExceeded && failure.resource?.metric == .operations) } + limits[.operations] = 3 + #expect(try JSONPatch.difference(from: source, to: target, options: .init(limits: limits)).operations.count == 3) + limits = .balanced; limits[.workUnits] = 10 + do { _ = try JSONPatch.difference(from: source, to: target, options: .init(limits: limits)); Issue.record("Expected a work limit failure") } + catch let failure as JSONFailure { #expect(failure.category == .resource) } + // Inputs are values; the difference never changes them. + #expect(source == (try parse(#"{"a":[1,2,3],"b":{"c":"x"}}"#))) + + let wide = JSON.array((0..<20_000).map { .number(JSONNumber(integer: $0)) }) + let task = Task { + while !Task.isCancelled { await Task.yield() } + _ = try JSONPatch.difference(from: wide, to: .array([])) + } + task.cancel() + do { try await task.value; Issue.record("Cancelled difference must throw") } + catch { #expect(error is CancellationError) } +}