Public Swift documentation
Exact JSON. Clear contracts.
-Keep decimal values exact, Unicode scalar keys distinct and resource use explicit. Explore five Swift libraries that carry those semantics from input bytes to validated, transformed and encoded output.
+Keep decimal values exact, Unicode scalar keys distinct and resource use explicit. Explore six Swift libraries that carry those semantics from input bytes to validated, transformed and encoded output.
Swift 6.4+ · Swift language mode 6 · macOS/SDK 27+ · No package dependencies
Start with the contract
diff --git a/Scripts/ci.py b/Scripts/ci.py
index d1e1d03..632ff34 100644
--- a/Scripts/ci.py
+++ b/Scripts/ci.py
@@ -25,7 +25,7 @@ def commands(lane, output):
# Root behavior/corpora remain required. SwiftData and Apple SDK/lifetime
# probes are separate Apple acceptance; they never become Linux passes.
return [c for c in commands('native', ROOT / output)
- if not any(x in c for x in ['Tools/MobileQualification', '--mode'])] + [
+ if not any(x in c for x in ['Tools/MobileQualification', '--mode', 'Scripts/qualify_cli_ownership.py'])] + [
['python3', '-B', 'Scripts/qualify_linux_reproduction.py', '--output', str(output / 'reproduction')]]
if lane == 'linux-safety':
# Every behavior case uses Swift Testing. Do not start the generated
@@ -53,6 +53,8 @@ def commands(lane, output):
['swift', 'run', '-c', 'release', '--package-path', 'Tools/JSONHTMLBrowser', 'BrowserFixtures', str(output / 'fixtures')],
['python3', '-B', 'Scripts/qualify_html_browser.py', '--fixtures', str(output / 'fixtures'), '--output', str(output / 'browser')],
]
+ if lane == 'cli':
+ return [['swift', 'build', '-c', 'release', '--product', 'swift-json'], ['swift', 'test', '--filter', 'cli'], ['python3', '-B', 'Scripts/qualify_cli.py', '--binary', '.build/release/swift-json', '--output', str(output / 'subprocess.json')]]
if lane == 'native':
return [
['python3', '-B', 'Scripts/public_check.py'],
@@ -61,6 +63,8 @@ def commands(lane, output):
['swift', 'build', '-c', 'release'],
['python3', '-B', 'Scripts/verify_testing_events.py'],
['swift', 'test'], ['swift', 'test', '-c', 'release'],
+ ['python3', '-B', 'Scripts/qualify_cli.py', '--binary', '.build/release/swift-json', '--output', str(output / 'subprocess.json')],
+ ['python3', '-B', 'Scripts/qualify_cli_ownership.py', '--output', str(output / 'cli-ownership')],
['python3', '-B', 'Scripts/qualify_release_1_1.py', '--mode', 'ownership', '--output', str(output / 'ownership.json')],
['python3', '-B', 'Scripts/qualify_release_1_1.py', '--mode', 'reader', '--output', str(output / 'reader.json')],
['swift', 'run', '-c', 'release', '--package-path', 'Examples/Consumer', 'Consumer'],
@@ -113,10 +117,12 @@ def check_result(command, code, log, events=None):
if events is not None:
counts = events['bundle_counts']
if command[:2] == ['swift', 'test']:
- expected = [38] if 'export|Export|apple' in command else [14] if 'Tools/WasmAudit' in command else [2, 3, 3, 11] if 'qa' in command else [7] if R0_TESTS in command else [3] if 'Tools/MCPReadiness' in command or 'Tools/MobileQualification' in command else [1] if 'Tools/Qualification' in command else [1, 1, 2, 3 if sys.platform == 'linux' else 4, 4] if 'thread' in command else sorted([10, 11, 12, 14, 61 if sys.platform == 'linux' else 75, 55, 119])
+ expected = [12] if 'cli' in command else [38] if 'export|Export|apple' in command else [14] if 'Tools/WasmAudit' in command else [2, 3, 3, 11] if 'qa' in command else [7] if R0_TESTS in command else [3] if 'Tools/MCPReadiness' in command or 'Tools/MobileQualification' in command else [1] if 'Tools/Qualification' in command else [1, 1, 2, 3 if sys.platform == 'linux' else 4, 4] if 'thread' in command else sorted([10, 11, 12, 12, 14, 61 if sys.platform == 'linux' else 75, 55, 119])
passed = passed and sorted(counts) == expected
if '--filter' not in command and not any(x.startswith('Tools/') for x in command):
- passed = passed and (events['parameterized_functions'] == ROOT_PARAMETER_CASES if events is not None else sum(int(n) for n in re.findall(r'with (\d+) test cases passed', log)) == 173)
+ if events is not None:
+ passed = passed and events['module_function_counts'] == {'JSONTests':119,'JSONBridgesTests':10,'JSONSchemaTests':55,'JSONStreamingTests':14,'JSONPatchTests':11,'JSONRegexRuntimeTests':12,'JSONHTMLTests':61 if sys.platform == 'linux' else 75,'JSONCLITests':12}
+ passed = passed and (events['parameterized_functions'] == ROOT_PARAMETER_CASES if events is not None else sum(int(n) for n in re.findall(r'with (\d+) test cases passed', log)) == 177)
if 'Tools/Qualification' in command:
probes = re.findall(r'^CAP_PROBE (\w+) (\S+)$', log, re.MULTILINE)
matrix = json.loads((ROOT / 'Documentation/Qualification/LimitsMatrix.json').read_text())
@@ -124,10 +130,10 @@ def check_result(command, code, log, events=None):
passed = passed and len(probes) == 49 and dict(probes) == expected_probes
if command == ['swift', 'package', 'dump-package'] and passed:
d = json.loads(log)
- passed = sorted(p['name'] for p in d['products']) == ['JSON', 'JSONBridges', 'JSONHTML', 'JSONPatch', 'JSONSchema', 'JSONStreaming'] and not d['dependencies'] and d['swiftLanguageVersions'] == ['6'] and d['toolsVersion']['_version'] == '6.4.0' and d['platforms'] == [{'options': [], 'platformName': 'macos', 'version': '27.0'}, {'options': [], 'platformName': 'ios', 'version': '27.0'}]
- passed = passed and {p['name']: p['targets'] for p in d['products']} == {name: [name] for name in ['JSON', 'JSONSchema', 'JSONStreaming', 'JSONPatch', 'JSONHTML', 'JSONBridges']}
+ passed = sorted(p['name'] for p in d['products']) == ['JSON', 'JSONBridges', 'JSONHTML', 'JSONPatch', 'JSONSchema', 'JSONStreaming', 'swift-json'] and not d['dependencies'] and d['swiftLanguageVersions'] == ['6'] and d['toolsVersion']['_version'] == '6.4.0' and d['platforms'] == [{'options': [], 'platformName': 'macos', 'version': '27.0'}, {'options': [], 'platformName': 'ios', 'version': '27.0'}]
+ passed = passed and {p['name']: p['targets'] for p in d['products']} == dict({name: [name] for name in ['JSON', 'JSONSchema', 'JSONStreaming', 'JSONPatch', 'JSONHTML', 'JSONBridges']}, **{'swift-json': ['JSONCLI']})
targets = {t['name']: t for t in d['targets']}
- passed = passed and set(targets) == {'JSON', 'JSONBridges', 'JSONSchema', 'JSONStreaming', 'JSONPatch', 'JSONHTML', 'JSONRegexRuntime', 'JSONTests', 'JSONBridgesTests', 'JSONSchemaTests', 'JSONStreamingTests', 'JSONPatchTests', 'JSONHTMLTests', 'JSONRegexRuntimeTests'} and targets['JSONHTML']['dependencies'] == [{'byName': ['JSON', None]}] and targets['JSONBridges']['dependencies'] == [{'byName': ['JSON', None]}]
+ passed = passed and set(targets) == {'JSON', 'JSONBridges', 'JSONBridgesTests', 'JSONSchema', 'JSONStreaming', 'JSONPatch', 'JSONHTML', 'JSONRegexRuntime', 'JSONTests', 'JSONSchemaTests', 'JSONStreamingTests', 'JSONPatchTests', 'JSONHTMLTests', 'JSONRegexRuntimeTests', 'JSONFilterRuntime', 'JSONCLIEngine', 'JSONCLI', 'JSONCLITests'} and targets['JSONHTML']['dependencies'] == [{'byName': ['JSON', None]}] and targets['JSONBridges']['dependencies'] == [{'byName': ['JSON', None]}] and targets['JSONFilterRuntime']['dependencies'] == [{'byName': ['JSON', None]}] and targets['JSONCLI']['type'] == 'executable'
if command == ['swift', 'package', 'show-dependencies', '--format', 'json'] and passed:
passed = json.loads(log)['dependencies'] == []
if command[:2] == ['swift', 'run'] and 'Tools/MobileQualification' in command:
@@ -146,7 +152,7 @@ def check_result(command, code, log, events=None):
def main():
parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument('--lane', choices=['native', 'safety', 'docs', 'r0', 'qa', 'linux', 'linux-safety', 'wasm', 'browser', 'export'], required=True)
+ parser.add_argument('--lane', choices=['native', 'safety', 'docs', 'r0', 'qa', 'linux', 'linux-safety', 'wasm', 'browser', 'export', 'cli'], required=True)
parser.add_argument('--output')
args = parser.parse_args()
output = ROOT / (args.output or '.build/ci/' + args.lane)
diff --git a/Scripts/qualify_cli.py b/Scripts/qualify_cli.py
new file mode 100644
index 0000000..8ce7f81
--- /dev/null
+++ b/Scripts/qualify_cli.py
@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Exercise the real CLI subprocess, exact bytes, exits, stderr and atomic files."""
+import argparse, hashlib, json, os, pathlib, signal, subprocess, tempfile, time
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+def main():
+ parser = argparse.ArgumentParser(); parser.add_argument('--binary', required=True); parser.add_argument('--output', required=True)
+ args = parser.parse_args(); binary = (ROOT / args.binary).resolve(); rows = []
+ def run(name, argv, data=b'', exit=0, expected=None, check=None):
+ command = [str(binary), *argv]; process = subprocess.run(command, input=data, capture_output=True, timeout=30)
+ ok = process.returncode == exit and (expected is None or process.stdout == expected)
+ if check: ok = ok and check(process)
+ rows.append({'id': name, 'command': ['swift-json', *[a if isinstance(a,str) else {'bytes_hex':a.hex()} for a in argv]], 'exit_code': process.returncode, 'expected_exit': exit,
+ 'stdout_sha256': hashlib.sha256(process.stdout).hexdigest(), 'stdout_bytes': len(process.stdout),
+ 'stderr_sha256': hashlib.sha256(process.stderr).hexdigest(), 'stderr_bytes': len(process.stderr), 'status': 'passed' if ok else 'failed'})
+ if not ok: print(name, process.returncode, repr(process.stdout[:250]), repr(process.stderr[:500]), flush=True)
+ return process
+ with tempfile.TemporaryDirectory(prefix='swift-json-cli-') as temp:
+ temp = pathlib.Path(temp)
+ def file(name, data):
+ path = temp / name; path.write_bytes(data); return str(path)
+ def limit(**caps): return file('limits.json', json.dumps({'version':1,'cli':caps}).encode())
+ run('help', ['--help'], check=lambda p: b'format' in p.stdout and not p.stderr)
+ run('invalid-argv-utf8', ['format', b'\xff'], exit=2, expected=b'', check=lambda p: b'invalidArgvUTF8' in p.stderr)
+ run('version', ['--version'], expected=b'swift-json 1.4.0-dev\n')
+ run('version-json', ['--version','--json'], check=lambda p: json.loads(p.stdout)['revision'] == 'unknown')
+ run('missing-command', [], exit=2, expected=b'')
+ run('unknown-option', ['format','--unknown'], exit=2, expected=b'')
+ run('usage-json-diagnostic', ['format','--diagnostics=json','--unknown'], exit=2, expected=b'', check=lambda p: json.loads(p.stderr)['kind'] == 'diagnostic' and json.loads(p.stderr)['category'] == 'usage')
+ run('duplicate-option', ['format','--compact','--compact'], exit=2, expected=b'')
+ run('indent-conflict', ['format','--compact','--tab'], exit=2, expected=b'')
+ run('preserved-numbers', ['format','--compact'], b'[9007199254740993,0.10,-0,1e1000]', expected=b'[9007199254740993,0.10,-0,1e1000]\n')
+ run('normalized-numbers', ['format','--compact','--number-style=normalized'], b'[0.10,-0]', expected=b'[1e-1,0]\n')
+ run('tab-indentation', ['format','--tab'], b'{"a":[1]}', expected=b'{\n\t"a": [\n\t\t1\n\t]\n}\n')
+ scalar = '{"é":1,"é":2}'.encode()
+ run('scalar-distinct-keys', ['format','-cS'], scalar, expected='{"é":2,"é":1}\n'.encode())
+ run('duplicate-decoded-key', ['format','--compact'], b'{"a":1,"\\u0061":2}', exit=5, expected=b'')
+ run('malformed-utf8', ['format'], b'"\xff"', exit=5, expected=b'')
+ run('trailing-root', ['format'], b'{} []', exit=5, expected=b'')
+ run('validation-syntax', ['validate'], b'{}', check=lambda p: json.loads(p.stdout) == {'valid':True,'issues':[],'truncated':False})
+ run('validation-malformed', ['validate'], b'{', exit=5, expected=b'')
+ schema = file('schema.json', b'{"type":"integer","minimum":3}')
+ run('schema-valid', ['validate','--schema',schema], b'4', check=lambda p: json.loads(p.stdout)['valid'] is True)
+ run('schema-invalid', ['validate','--schema',schema], b'2', exit=1, check=lambda p: json.loads(p.stdout)['valid'] is False and len(json.loads(p.stdout)['issues']) > 0)
+ run('schema-bounded-issues', ['validate','--schema',schema,'--max-issues','0'], b'2', exit=1, check=lambda p: json.loads(p.stdout) == {'valid':False,'issues':[],'truncated':True})
+ run('pointer-null', ['pointer','/a'], b'{"a":null}', expected=b'null\n')
+ run('pointer-missing', ['pointer','/a'], b'{}', exit=5, expected=b'')
+ run('pointer-allow-missing', ['pointer','/a','--allow-missing'], b'{}', exit=4, expected=b'')
+ run('pointer-array-absence', ['pointer','/0','--allow-missing'], b'[]', exit=4, expected=b'')
+ run('pointer-malformed-index-stays-error', ['pointer','/01','--allow-missing'], b'[]', exit=5, expected=b'')
+ run('pointer-wrong-type', ['pointer','/a','--allow-missing'], b'[]', exit=5, expected=b'')
+ run('pointer-escaped-key', ['pointer','/a~1b~0c'], b'{"a/b~c":1}', expected=b'1\n')
+ patch = file('patch.json', b'[{"op":"remove","path":""}]')
+ run('patch-root-absence', ['patch','--patch',patch], b'null', expected=b'')
+ patch = file('patch.json', b'[{"op":"add","path":"/b","value":9007199254740993}]')
+ run('patch-exact-value', ['patch','--patch',patch], b'{"a":1}', check=lambda p: b'9007199254740993' in p.stdout)
+ patch = file('patch.json', b'[{"op":"add","path":"/b","value":2},{"op":"test","path":"/a","value":0}]')
+ run('patch-failure-no-candidate', ['patch','--patch',patch], b'{"a":1}', exit=5, expected=b'')
+ run('html-invalid-title-is-usage', ['render','--title','\x01'], b'{}', exit=2, expected=b'')
+ run('static-html', ['render'], b'{"x":"