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) } +}