Skip to content

Commit 771f088

Browse files
JE-ChenJE-Chen
committed
Rename JSON snapshot to snapshot_json to avoid facade name clash
1 parent 3cab323 commit 771f088

10 files changed

Lines changed: 26 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@
127127

128128
Match, diff and snapshot JSON payloads. Full reference: [`docs/source/Eng/doc/new_features/v70_features_doc.rst`](docs/source/Eng/doc/new_features/v70_features_doc.rst).
129129

130-
- **`match_json` / `diff_json` / `normalize_json` / `snapshot`** (`AC_match_json`, `AC_diff_json`): `json_schema` validates against an authored schema and `jsonpath` extracts, but nothing matched two payloads with relaxed rules or diffed them path-by-path. This adds contract/snapshot matching — `partial` (subset), `match_type` (Pact-style `like`), `ignore` volatile paths — returning `{path, kind}` mismatches (`missing`/`extra`/`changed`), plus golden-master `snapshot`. Composes with `json_schema` + `json_patch`; pure-stdlib.
130+
- **`match_json` / `diff_json` / `normalize_json` / `snapshot_json`** (`AC_match_json`, `AC_diff_json`): `json_schema` validates against an authored schema and `jsonpath` extracts, but nothing matched two payloads with relaxed rules or diffed them path-by-path. This adds contract/snapshot matching — `partial` (subset), `match_type` (Pact-style `like`), `ignore` volatile paths — returning `{path, kind}` mismatches (`missing`/`extra`/`changed`), plus golden-master `snapshot_json`. Composes with `json_schema` + `json_patch`; pure-stdlib.
131131

132132
## What's new (2026-06-21) — SLSA Build Provenance
133133

‎README/README_zh-CN.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@
126126

127127
比对、取差异与快照 JSON 内容。完整参考:[`docs/source/Zh/doc/new_features/v70_features_doc.rst`](../docs/source/Zh/doc/new_features/v70_features_doc.rst)。
128128

129-
- **`match_json` / `diff_json` / `normalize_json` / `snapshot`**(`AC_match_json`、`AC_diff_json`):`json_schema` 以撰写的 schema 验证、`jsonpath` 提取,但没有任何东西能以宽松规则比对两份内容或逐路径取差异。本功能补上合约/快照比对 —— `partial`(子集)、`match_type`(Pact 风格 `like`)、`ignore` 易变路径 —— 返回 `{path, kind}` 不符(`missing`/`extra`/`changed`),外加 golden-master `snapshot`。与 `json_schema` + `json_patch` 互补;纯标准库。
129+
- **`match_json` / `diff_json` / `normalize_json` / `snapshot_json`**(`AC_match_json`、`AC_diff_json`):`json_schema` 以撰写的 schema 验证、`jsonpath` 提取,但没有任何东西能以宽松规则比对两份内容或逐路径取差异。本功能补上合约/快照比对 —— `partial`(子集)、`match_type`(Pact 风格 `like`)、`ignore` 易变路径 —— 返回 `{path, kind}` 不符(`missing`/`extra`/`changed`),外加 golden-master `snapshot_json`。与 `json_schema` + `json_patch` 互补;纯标准库。
130130

131131
## 本次更新 (2026-06-21) — SLSA 构建来源证明
132132

‎README/README_zh-TW.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@
126126

127127
比對、取差異與快照 JSON 內容。完整參考:[`docs/source/Zh/doc/new_features/v70_features_doc.rst`](../docs/source/Zh/doc/new_features/v70_features_doc.rst)。
128128

129-
- **`match_json` / `diff_json` / `normalize_json` / `snapshot`**(`AC_match_json`、`AC_diff_json`):`json_schema` 以撰寫的 schema 驗證、`jsonpath` 擷取,但沒有任何東西能以寬鬆規則比對兩份內容或逐路徑取差異。本功能補上合約/快照比對 —— `partial`(子集)、`match_type`(Pact 風格 `like`)、`ignore` 易變路徑 —— 回傳 `{path, kind}` 不符(`missing`/`extra`/`changed`),外加 golden-master `snapshot`。與 `json_schema` + `json_patch` 互補;純標準函式庫。
129+
- **`match_json` / `diff_json` / `normalize_json` / `snapshot_json`**(`AC_match_json`、`AC_diff_json`):`json_schema` 以撰寫的 schema 驗證、`jsonpath` 擷取,但沒有任何東西能以寬鬆規則比對兩份內容或逐路徑取差異。本功能補上合約/快照比對 —— `partial`(子集)、`match_type`(Pact 風格 `like`)、`ignore` 易變路徑 —— 回傳 `{path, kind}` 不符(`missing`/`extra`/`changed`),外加 golden-master `snapshot_json`。與 `json_schema` + `json_patch` 互補;純標準函式庫。
130130

131131
## 本次更新 (2026-06-21) — SLSA 建置來源證明
132132

‎docs/source/Eng/doc/new_features/v70_features_doc.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Headless API
1414

1515
.. code-block:: python
1616
17-
from je_auto_control import match_json, diff_json, snapshot
17+
from je_auto_control import match_json, diff_json, snapshot_json
1818
1919
report = match_json(actual, {"id": 1, "name": "Ada"})
2020
if not report.ok:
@@ -29,7 +29,7 @@ Headless API
2929
match_json(response, template, ignore=["$.created_at", "$.id"])
3030
3131
diff_json(actual, expected) # [{path, kind, ...}]
32-
snapshot(actual, "golden/checkout.json") # write-if-absent, else compare
32+
snapshot_json(actual, "golden/checkout.json") # write-if-absent, else compare
3333
3434
``match_json`` returns a ``MatchReport(ok, mismatches)`` where each mismatch is
3535
``{path, kind}`` with ``kind`` one of ``missing`` (in expected, absent from
@@ -38,7 +38,7 @@ actual), ``extra`` (in actual, absent from expected), or ``changed``. Options:
3838
``changed`` leaf whose types match (Pact ``like``), and ``ignore`` skips listed
3939
paths. ``diff_json`` is the raw path-tagged diff; ``normalize_json`` returns a
4040
canonical copy (sorted keys, ``drop`` keys removed) for stable comparison;
41-
``snapshot`` is golden-master testing (writes the file on first run, then
41+
``snapshot_json`` is golden-master testing (writes the file on first run, then
4242
matches against it). ``true`` stays distinct from ``1``.
4343

4444
Executor commands

‎docs/source/Zh/doc/new_features/v70_features_doc.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ JSON 合約與快照比對
1212

1313
.. code-block:: python
1414
15-
from je_auto_control import match_json, diff_json, snapshot
15+
from je_auto_control import match_json, diff_json, snapshot_json
1616
1717
report = match_json(actual, {"id": 1, "name": "Ada"})
1818
if not report.ok:
@@ -27,13 +27,13 @@ JSON 合約與快照比對
2727
match_json(response, template, ignore=["$.created_at", "$.id"])
2828
2929
diff_json(actual, expected) # [{path, kind, ...}]
30-
snapshot(actual, "golden/checkout.json") # 不存在則寫入,否則比對
30+
snapshot_json(actual, "golden/checkout.json") # 不存在則寫入,否則比對
3131
3232
``match_json`` 回傳 ``MatchReport(ok, mismatches)``,每個不符為 ``{path, kind}``,``kind`` 為
3333
``missing``(在 expected、actual 沒有)、``extra``(在 actual、expected 沒有)或 ``changed`` 之一。
3434
選項:``partial`` 捨棄 ``extra`` 不符(子集比對),``match_type`` 接受型別相符的 ``changed`` 葉
3535
(Pact ``like``),``ignore`` 略過列出的路徑。``diff_json`` 是原始的路徑標記差異;``normalize_json``
36-
回傳正規化副本(鍵排序、移除 ``drop`` 鍵)以利穩定比對;``snapshot`` 是 golden-master 測試
36+
回傳正規化副本(鍵排序、移除 ``drop`` 鍵)以利穩定比對;``snapshot_json`` 是 golden-master 測試
3737
(首次執行寫檔,之後比對)。``true`` 與 ``1`` 保持相異。
3838

3939
執行器命令

‎je_auto_control/__init__.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -358,7 +358,7 @@
358358
)
359359
# JSON contract / snapshot matching
360360
from je_auto_control.utils.json_contract import (
361-
MatchReport, diff_json, match_json, normalize_json, snapshot,
361+
MatchReport, diff_json, match_json, normalize_json, snapshot_json,
362362
)
363363
# Background popup/interrupt watchdog (unattended automation)
364364
from je_auto_control.utils.watchdog import (
@@ -852,7 +852,7 @@ def start_autocontrol_gui(*args, **kwargs):
852852
"percentage_bucket",
853853
"build_provenance", "subject_for", "subject_for_bytes",
854854
"verify_provenance", "write_provenance",
855-
"MatchReport", "diff_json", "match_json", "normalize_json", "snapshot",
855+
"MatchReport", "diff_json", "match_json", "normalize_json", "snapshot_json",
856856
# MCP server
857857
"AuditLogger", "HttpMCPServer", "MCPContent", "MCPPrompt",
858858
"MCPPromptArgument", "MCPResource", "MCPServer", "MCPTool",

‎je_auto_control/gui/script_builder/command_schema.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1158,8 +1158,10 @@ def _add_misc_specs(specs: List[CommandSpec]) -> None:
11581158
specs.append(CommandSpec(
11591159
"AC_match_json", "Data", "JSON Contract: Match",
11601160
fields=(
1161-
FieldSpec("actual", FieldType.STRING, placeholder='{"a": 1}'),
1162-
FieldSpec("expected", FieldType.STRING, placeholder='{"a": 1}'),
1161+
FieldSpec("actual", FieldType.STRING,
1162+
placeholder='{"id": 1, "name": "Ada"}'),
1163+
FieldSpec("expected", FieldType.STRING,
1164+
placeholder='{"id": 1, "name": "Ada"}'),
11631165
FieldSpec("partial", FieldType.BOOL, optional=True, default=False),
11641166
FieldSpec("match_type", FieldType.BOOL, optional=True,
11651167
default=False),
@@ -1169,8 +1171,8 @@ def _add_misc_specs(specs: List[CommandSpec]) -> None:
11691171
specs.append(CommandSpec(
11701172
"AC_diff_json", "Data", "JSON Contract: Diff",
11711173
fields=(
1172-
FieldSpec("actual", FieldType.STRING, placeholder='{"a": 1}'),
1173-
FieldSpec("expected", FieldType.STRING, placeholder='{"a": 2}'),
1174+
FieldSpec("actual", FieldType.STRING, placeholder='[1, 2, 3]'),
1175+
FieldSpec("expected", FieldType.STRING, placeholder='[1, 2]'),
11741176
),
11751177
description="Path-tagged diff between two JSON payloads; {diffs}.",
11761178
))

‎je_auto_control/utils/json_contract/__init__.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
"""JSON contract / snapshot matching: match_json, diff_json, snapshot."""
1+
"""JSON contract / snapshot matching: match_json, diff_json, snapshot_json."""
22
from je_auto_control.utils.json_contract.json_contract import (
3-
MatchReport, diff_json, match_json, normalize_json, snapshot,
3+
MatchReport, diff_json, match_json, normalize_json, snapshot_json,
44
)
55

66
__all__ = [
7-
"MatchReport", "diff_json", "match_json", "normalize_json", "snapshot",
7+
"MatchReport", "diff_json", "match_json", "normalize_json", "snapshot_json",
88
]

‎je_auto_control/utils/json_contract/json_contract.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ def normalize_json(value: Any, *, drop: Iterable[str] = ()) -> Any:
115115
return _normalize(value, set(drop))
116116

117117

118-
def snapshot(actual: Any, path: str) -> bool:
118+
def snapshot_json(actual: Any, path: str) -> bool:
119119
"""Golden-master: write ``actual`` if absent, else match the saved copy."""
120120
target = Path(os.path.realpath(path))
121121
if not target.exists():

‎test/unit_test/headless/test_json_contract_batch.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
import je_auto_control as ac
55
from je_auto_control.utils.json_contract import (
6-
MatchReport, diff_json, match_json, normalize_json, snapshot)
6+
MatchReport, diff_json, match_json, normalize_json, snapshot_json)
77

88

99
def test_exact_match():
@@ -63,9 +63,9 @@ def test_normalize_sorts_and_drops():
6363

6464
def test_snapshot_create_then_compare(tmp_path):
6565
path = str(tmp_path / "snap.json")
66-
assert snapshot({"x": 1}, path) is True # created
67-
assert snapshot({"x": 1}, path) is True # matches
68-
assert snapshot({"x": 2}, path) is False # differs
66+
assert snapshot_json({"x": 1}, path) is True # created
67+
assert snapshot_json({"x": 1}, path) is True # matches
68+
assert snapshot_json({"x": 2}, path) is False # differs
6969

7070

7171
# --- wiring ---------------------------------------------------------------
@@ -98,7 +98,7 @@ def test_wiring():
9898

9999

100100
def test_facade_exports():
101-
for attr in ("match_json", "diff_json", "normalize_json", "snapshot",
101+
for attr in ("match_json", "diff_json", "normalize_json", "snapshot_json",
102102
"MatchReport"):
103103
assert hasattr(ac, attr)
104104
assert attr in ac.__all__

0 commit comments

Comments
 (0)