Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@
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.
- Add `JSONHTMLRenderer.renderDifference(from:to:)` and
`renderDifferenceWithReport`, a static, script-free page that shows two exact
values as one combined tree. Added, removed and changed values carry
text markers as well as color; equal values stay visible but collapsed. A
summary, a change list linked by JSON Pointer, a CSS-only "Show changes only"
toggle and native downloads of the RFC 6902 patch, the source and the target
complete the page. Its CSP authorizes the two stylesheets by hash and sets
`script-src 'none'`. The comparison is a package walker in JSON shared with
`JSONPatch.difference`, so JSONHTML still depends on JSON only.

## Unreleased — 1.9.1 hygiene

Expand Down
6 changes: 3 additions & 3 deletions Documentation/Qualification/TestDiscovery.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
"JSONStreamingTests": 36,
"JSONPatchTests": 22,
"JSONIntegrationTests": 45,
"JSONHTMLTests": 97,
"JSONHTMLTests": 103,
"JSONBridgesTests": 10,
"JSONCLITests": 88,
"JSONNavigationTests": 57,
Expand Down Expand Up @@ -79,7 +79,7 @@
"JSONStreamingTests": 36,
"JSONPatchTests": 22,
"JSONIntegrationTests": 45,
"JSONHTMLTests": 81,
"JSONHTMLTests": 87,
"JSONBridgesTests": 10,
"JSONCLITests": 88,
"JSONNavigationTests": 57,
Expand All @@ -95,7 +95,7 @@
"JSONStreamingTests": 36,
"JSONPatchTests": 22,
"JSONIntegrationTests": 45,
"JSONHTMLTests": 81,
"JSONHTMLTests": 87,
"JSONBridgesTests": 10,
"JSONNavigationTests": 57,
"JSONSchemaExamplesTests": 98,
Expand Down
2 changes: 1 addition & 1 deletion Scripts/ci.py
Original file line number Diff line number Diff line change
Expand Up @@ -533,7 +533,7 @@ def check_result(command, code, log, events=None):
if command[:3] == ['python3', '-B', 'Scripts/qualify_navigation.py']:
passed = passed and 'NAVIGATION_COMPILER passed configurations=2 consumer_cases=18 negative_probes=8' in log.splitlines()
if command[:3] == ['python3', '-B', 'Scripts/verify_html_assets.py']:
passed = passed and 'JSONHTML_ASSETS passed count=2' in log.splitlines()
passed = passed and 'JSONHTML_ASSETS passed count=3' in log.splitlines()
if 'BrowserFixtures' in command:
passed = passed and 'JSONHTML_BROWSER_FIXTURES passed count=15' in log.splitlines()
if command[:3] == ['python3', '-B', 'Scripts/qualify_html_browser.py']:
Expand Down
15 changes: 10 additions & 5 deletions Scripts/verify_html_assets.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,14 @@ def expected(root):
js = (root / 'Sources/JSONHTML/Assets/Interactive.js').read_text().rstrip('\n')
def digest(t): return base64.b64encode(hashlib.sha256(t.encode()).digest()).decode()
return '// SPDX-License-Identifier: Apache-2.0\n// Generated from Assets; verify with Scripts/verify_html_assets.py.\npackage enum JSONHTMLInteractiveAssets {\n package static let base64Alphabet: [UInt8] = Array("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".utf8)\n package static let css = #"""\n' + css + '\n"""#\n package static let script = #"""\n' + js + '\n"""#\n package static let styleHash = "' + digest(base + '\n' + css) + '"\n package static let scriptHash = "' + digest(js) + '"\n}\n'
def expected_difference(root):
css = (root / 'Sources/JSONHTML/Assets/Difference.css').read_text().rstrip('\n')
digest = base64.b64encode(hashlib.sha256(css.encode()).digest()).decode()
return '// SPDX-License-Identifier: Apache-2.0\n// Fixed difference CSS from Assets/Difference.css; CSP hashes exactly these UTF-8 bytes.\npackage enum JSONHTMLDifferenceAssets {\n package static let css = #"""\n' + css + '\n"""#\n package static let cssHash = "' + digest + '"\n}\n'
if __name__ == '__main__':
target = ROOT / 'Sources/JSONHTML/JSONHTMLInteractiveAssets.swift'
text = expected(ROOT)
if sys.argv[1:] == ['--write']: target.write_text(text)
if target.read_text() != text: raise SystemExit('Interactive asset mirror or CSP hash mismatch')
print('JSONHTML_ASSETS passed count=2')
mirrors = [(ROOT / 'Sources/JSONHTML/JSONHTMLInteractiveAssets.swift', expected(ROOT), 'Interactive'),
(ROOT / 'Sources/JSONHTML/JSONHTMLDifferenceAssets.swift', expected_difference(ROOT), 'Difference')]
for target, text, name in mirrors:
if sys.argv[1:] == ['--write']: target.write_text(text)
if target.read_text() != text: raise SystemExit(f'{name} asset mirror or CSP hash mismatch')
print('JSONHTML_ASSETS passed count=3')
201 changes: 201 additions & 0 deletions Sources/JSON/Value/JSONStructuralDifference.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,201 @@
// SPDX-License-Identifier: Apache-2.0
// Original bounded structural difference shared by JSONPatch and JSONHTML.

/// One step of a merged walk over two values, in display order.
///
/// A value event (`same`, `added`, `removed`, `replaced`, `beginObject`,
/// `beginArray`) follows a `member` or `element` event, except at the root.
package enum JSONDifferenceEvent: Sendable {
/// The value is equal on both sides (exact model equality).
case same(JSON)
/// The value exists only in the target.
case added(JSON)
/// The value exists only in the source.
case removed(JSON)
/// Different kinds or unequal scalars: the source value is replaced.
case replaced(source: JSON, target: JSON)
/// Both sides are unequal objects; member events follow until `endObject`.
case beginObject
case endObject
/// Both sides are unequal arrays; element events follow until `endArray`.
case beginArray
case endArray
/// The next value event belongs to this object member.
case member(JSONKey)
/// The next value event belongs to this element; the position is nil on the side that lacks it.
case element(source: Int?, target: Int?)
/// A run of equal array elements, kept as one event.
case sameElements(ArraySlice<JSON>, sourceStart: Int, targetStart: Int)
}

/// A neutral RFC 6902 operation produced from the shared difference.
package struct JSONDifferenceOperation: Sendable {
package enum Kind: Sendable { case add, remove, replace }
package let kind: Kind
package let path: [JSONKey]
package let value: JSON?
}

/// Walks two admitted values and yields ``JSONDifferenceEvent``s on the caller's meter.
///
/// Objects list source members in source order (compared or removed), then target-only
/// members in target order. Arrays keep the longest equal prefix and suffix, compare
/// the remaining elements by position, then list surplus source elements (removed)
/// and surplus target elements (added) in ascending order.
package struct JSONDifferenceWalker {
private enum Frame {
case compare(JSON, JSON)
case object(JSONObject, JSONObject, phase: Int, index: Int)
case array([JSON], [JSON], prefix: Int, suffix: Int, step: Int)
}
private var frames: [Frame]
private var queued: [JSONDifferenceEvent] = []
private var started = false

package init(source: JSON, target: JSON) { frames = [.compare(source, target)] }

package mutating func next(meter: inout JSONWorkMeter) throws -> JSONDifferenceEvent? {
if !started { try meter.retain(JSONLogicalWeights.frame); started = true }
while true {
try meter.work()
if !queued.isEmpty { return queued.removeFirst() }
guard let frame = frames.popLast() else { return nil }
try meter.release(JSONLogicalWeights.frame)
switch frame {
case .compare(let a, let b):
if try JSONComparison.equals(a, b, meter: &meter) { return .same(b) }
switch (a, b) {
case (.object(let x), .object(let y)):
try push(.object(x, y, phase: 0, index: 0), meter: &meter); return .beginObject
case (.array(let x), .array(let y)):
let shared = min(x.count, y.count)
var prefix = 0
while prefix < shared, try JSONComparison.equals(x[prefix], y[prefix], meter: &meter) { prefix += 1 }
var suffix = 0
while suffix < shared - prefix,
try JSONComparison.equals(x[x.count - 1 - suffix], y[y.count - 1 - suffix], meter: &meter) { suffix += 1 }
try push(.array(x, y, prefix: prefix, suffix: suffix, step: 0), meter: &meter); return .beginArray
default:
return .replaced(source: a, target: b)
}
case .object(let a, let b, let phase, let index):
if phase == 0, index < a.count {
let member = a[index]
try push(.object(a, b, phase: 0, index: index + 1), meter: &meter)
if let counterpart = try b.lookup(member.key.string, meter: &meter) {
try push(.compare(member.value, counterpart), meter: &meter)
} else {
queued.append(.removed(member.value))
}
return .member(member.key)
}
var position = phase == 0 ? 0 : index
while position < b.count {
try meter.work()
let member = b[position]; position += 1
if try a.lookup(member.key.string, meter: &meter) == nil {
try push(.object(a, b, phase: 1, index: position), meter: &meter)
queued.append(.added(member.value))
return .member(member.key)
}
}
return .endObject
case .array(let a, let b, let prefix, let suffix, let step):
let middleA = a.count - prefix - suffix, middleB = b.count - prefix - suffix
let paired = min(middleA, middleB)
// Steps: 0 prefix run, then pairs, removals, additions, suffix run, end.
var next = step
if next == 0 {
next = 1
if prefix > 0 {
try push(.array(a, b, prefix: prefix, suffix: suffix, step: next), meter: &meter)
return .sameElements(b[0..<prefix], sourceStart: 0, targetStart: 0)
}
}
let pairedEnd = 1 + paired, removedEnd = pairedEnd + middleA - paired, addedEnd = removedEnd + middleB - paired
if next < pairedEnd {
let position = prefix + next - 1
try push(.array(a, b, prefix: prefix, suffix: suffix, step: next + 1), meter: &meter)
try push(.compare(a[position], b[position]), meter: &meter)
return .element(source: position, target: position)
}
if next < removedEnd {
let position = prefix + paired + (next - pairedEnd)
try push(.array(a, b, prefix: prefix, suffix: suffix, step: next + 1), meter: &meter)
queued.append(.removed(a[position]))
return .element(source: position, target: nil)
}
if next < addedEnd {
let position = prefix + paired + (next - removedEnd)
try push(.array(a, b, prefix: prefix, suffix: suffix, step: next + 1), meter: &meter)
queued.append(.added(b[position]))
return .element(source: nil, target: position)
}
if next == addedEnd, suffix > 0 {
try push(.array(a, b, prefix: prefix, suffix: suffix, step: next + 1), meter: &meter)
return .sameElements(b[(b.count - suffix)...], sourceStart: a.count - suffix, targetStart: b.count - suffix)
}
return .endArray
}
}
}
private mutating func push(_ frame: Frame, meter: inout JSONWorkMeter) throws {
try meter.retain(JSONLogicalWeights.frame); frames.append(frame)
}

/// RFC 6902 operations for the same difference, in an order that applies cleanly:
/// within an array, paired changes first, then removals from the highest index
/// down, then additions in ascending order.
package static func operations(from source: JSON, to target: JSON, meter: inout JSONWorkMeter) throws -> [JSONDifferenceOperation] {
struct Level { var removals: [JSONDifferenceOperation] = []; var additions: [JSONDifferenceOperation] = [] }
var walker = JSONDifferenceWalker(source: source, target: target)
var operations: [JSONDifferenceOperation] = []
var path: [JSONKey] = [], levels: [Level?] = []
var pendingKey: JSONKey? = nil, pendingElement = false
func emit(_ operation: JSONDifferenceOperation, meter: inout JSONWorkMeter) throws {
try meter.require(.operations, UInt64(operations.count) + 1)
try meter.retain(JSONLogicalWeights.frame); operations.append(operation)
}
func childPath(meter: inout JSONWorkMeter) throws -> [JSONKey] {
guard let pendingKey else { return path }
try meter.require(.pointerTokens, UInt64(path.count) + 1)
for _ in path { try meter.work() }
try meter.retain(16)
return path + [pendingKey]
}
func deferred(_ operation: JSONDifferenceOperation, removal: Bool, meter: inout JSONWorkMeter) throws {
guard pendingElement, let last = levels.indices.last, levels[last] != nil else { return try emit(operation, meter: &meter) }
try meter.retain(JSONLogicalWeights.frame)
if removal { levels[last]!.removals.append(operation) } else { levels[last]!.additions.append(operation) }
}
while let event = try walker.next(meter: &meter) {
switch event {
case .member(let key): pendingKey = key; pendingElement = false
case .element(let s, let t):
pendingKey = try JSONKey(String(s ?? t ?? 0), meter: &meter); pendingElement = s == nil || t == nil
case .same, .sameElements: pendingKey = nil; pendingElement = false
case .replaced(_, let value):
try emit(.init(kind: .replace, path: childPath(meter: &meter), value: value), meter: &meter)
pendingKey = nil; pendingElement = false
case .removed:
try deferred(.init(kind: .remove, path: childPath(meter: &meter), value: nil), removal: true, meter: &meter)
pendingKey = nil; pendingElement = false
case .added(let value):
try deferred(.init(kind: .add, path: childPath(meter: &meter), value: value), removal: false, meter: &meter)
pendingKey = nil; pendingElement = false
case .beginObject, .beginArray:
path = try childPath(meter: &meter); pendingKey = nil; pendingElement = false
try meter.retain(JSONLogicalWeights.frame)
if case .beginArray = event { levels.append(Level()) } else { levels.append(nil) }
case .endObject, .endArray:
if let level = levels.removeLast() {
for operation in level.removals.reversed() { try emit(operation, meter: &meter) }
for operation in level.additions { try emit(operation, meter: &meter) }
}
try meter.release(JSONLogicalWeights.frame)
if !path.isEmpty { path.removeLast() }
}
}
return operations
}
}
2 changes: 1 addition & 1 deletion Sources/JSONCLIEngine/CLIBuildIdentity.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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:ab828e1c70d46c10f7a6431f5e9ef22ac469b8609778e3e99b7a0f6af77891ff"
package static let revision = "sha256:dafab040289a71fed6924ffe8aa7a7273e6315c5701d1fd35fd5d1b812a52ccd"
package static let kind = "source-sha256"
}
15 changes: 15 additions & 0 deletions Sources/JSONHTML/Assets/Difference.css

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading