# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """Addresses, anchors and their resolution (spec/06).""" import json from fractions import Fraction import pytest from hypothesis import given, settings, strategies as st from conftest import ROOT from helpers_lib1 import ( HALE, build_doc, case_params, document, heading, ids_of_kind, package_state, paragraph, read_cases, sentence, text_run, vectors, ) from paperspec import anchors, hashing from paperspec.corrections import State from paperspec.model import LEAVES from paperspec.text import norm PROPERTIES = settings(derandomize=True, max_examples=200, database=None, deadline=None) FIRST = "Harmonic bond terms remain the most common description of covalent stretching." SECOND = "Every bond was scanned in steps of small size around its minimum energy." THIRD = "The charges came from a two-stage restrained fit to the potential." FOURTH = "Torsions were refit against a second, larger set of conformers." KEYS = st.builds( lambda head, tail, sfx: f"{head}-{tail}" + "".join(f".{s}" for s in sfx), st.from_regex(r"[a-z][a-z0-9]{0,8}", fullmatch=True), st.text(alphabet="0123456789abcdefghjkmnpqrstvwxyz", min_size=4, max_size=12), st.lists(st.from_regex(r"[a-z0-9][a-z0-9-]{0,4}", fullmatch=True), max_size=2), ) NAMES = st.from_regex(r"[a-z0-9][a-z0-9._-]{0,10}", fullmatch=True) @pytest.mark.parametrize("case", vectors("addresses")) def test_address_vector_parses(case): assert anchors.parse_address(case["address"]) == case["parsed"] @pytest.mark.parametrize( "case", case_params([c for c in read_cases("addresses") if c["parsed"]]) ) def test_address_vector_formats_back(case): parts = case["parsed"] got = anchors.format_address( parts["store"], parts["key"], parts["node"], parts["pin"], parts["span"] ) assert got == case["address"] @given( st.one_of(st.none(), NAMES), KEYS, NAMES, st.one_of(st.none(), st.text(alphabet="0123456789abcdef", min_size=6, max_size=6)), st.one_of( st.none(), st.tuples(st.integers(0, 10**6), st.integers(0, 10**6)).map(sorted) ), ) @PROPERTIES def test_a_formatted_address_parses_back(store, key, node, pin, span): address = anchors.format_address(store, key, node, pin, span) assert anchors.parse_address(address) == { "store": store, "key": key, "node": node, "pin": pin, "span": span, } @given(st.text(max_size=40)) @PROPERTIES def test_parsing_any_text_gives_an_address_or_none(text): parsed = anchors.parse_address(text) assert parsed is None or anchors.format_address(**parsed) == text def test_format_address_keeps_six_characters_of_a_longer_pin(): assert ( anchors.format_address(None, "a-bcde", "n1", "0123456789abcdef") == "a-bcde#n1@012345" ) @pytest.mark.parametrize( ("store", "pin", "span", "tail"), [ ("", None, None, ""), (None, "", None, ""), (None, None, [3, 9], "[3:9]"), (None, None, (0, 0), "[0:0]"), ], ) def test_format_address_leaves_out_what_is_empty(store, pin, span, tail): assert ( anchors.format_address(store, "a-bcde", "n1", pin, span) == "a-bcde#n1" + tail ) # --- making anchors ----------------------------------------------------------------- def _tree(): return build_doc( document( { "kind": "section", "label": "1", "attrs": {"level": 1}, "children": [ heading("Methods"), paragraph(sentence(text_run(FIRST)), sentence(text_run(SECOND))), paragraph(sentence(text_run(THIRD)), sentence(text_run(FOURTH))), ], } ) ) def _state(doc, ids=(), corrections=()): return State(doc.key, [doc.nodes[n] for n in doc.order], ids, corrections) def _anchor(state, nid, rev=0, span=None, store=None): doc = state.doc() return anchors.make_anchor(doc, hashing.compute(doc), nid, rev, span, store) def _edit(state, texts, drop=(), ids=(), corrections=(), move=None): """A later state: sentence texts replaced, nodes dropped, optionally one node re-parented.""" nodes = [] for original in state.nodes: if original["id"] in drop: continue n = dict(original) if n["id"] in texts: n["content"] = [text_run(texts[n["id"]])] if move and n["id"] == move[0]: n["parent"], n["ord"] = move[1], move[2] nodes.append(n) return State( state.key, nodes, list(state.ids) + list(ids), list(state.corrections) + list(corrections), ) @pytest.fixture def tree(): doc = _tree() state = _state(doc) sentences = ids_of_kind(doc, "sentence") paragraphs = ids_of_kind(doc, "paragraph") return { "state": state, "section": ids_of_kind(doc, "section")[0], "heading_sentence": sentences[0], "s1": sentences[1], "s2": sentences[2], "s3": sentences[3], "s4": sentences[4], "p1": paragraphs[0], "p2": paragraphs[1], } class TestMakeAnchor: def test_a_leaf_anchor_holds_its_hashes_and_the_whole_text_as_the_quote(self, tree): state = tree["state"] doc = state.doc() values = hashing.compute(doc) a = _anchor(state, tree["s1"], rev=7, store="smithlab") assert a == { "format": "scienting-anchor/1", "store": "smithlab", "doc": doc.key, "node": tree["s1"], "kind": "sentence", "own_hash": values[tree["s1"]]["own_hash"], "node_hash": values[tree["s1"]]["node_hash"], "quote": {"exact": FIRST}, "rev": 7, } def test_without_a_store_there_is_no_store_member(self, tree): assert "store" not in _anchor(tree["state"], tree["s1"]) def test_a_span_gives_the_quote_with_its_context(self, tree): start = FIRST.index("description") span = [start, start + len("description")] a = _anchor(tree["state"], tree["s1"], span=span) assert a["span"] == span assert a["quote"] == { "exact": "description", "prefix": FIRST[max(0, start - 32) : start], "suffix": FIRST[span[1] : span[1] + 32], } assert len(a["quote"]["prefix"]) == 32 def test_a_span_at_the_ends_leaves_out_the_empty_context(self, tree): a = _anchor(tree["state"], tree["s1"], span=[0, 8]) assert a["quote"] == {"exact": FIRST[:8], "suffix": FIRST[8:40]} end = len(FIRST) b = _anchor(tree["state"], tree["s1"], span=(end - 5, end)) assert b["span"] == [end - 5, end] assert b["quote"] == {"exact": FIRST[-5:], "prefix": FIRST[end - 37 : end - 5]} def test_a_long_quote_is_held_by_its_hash_and_length(self): long_text = "word " * 50 + "end." doc = build_doc( document( { "kind": "section", "attrs": {"level": 1}, "children": [ heading("H"), paragraph(sentence(text_run(long_text))), ], } ) ) state = _state(doc) (nid,) = [ n for n in ids_of_kind(doc, "sentence") if len(hashing.plain(doc, n)) > 200 ] a = _anchor(state, nid) assert a["quote"] == { "exact_hash": hashing.PLAIN(long_text), "length": len(long_text), } short = _anchor(state, nid, span=[0, 200]) assert short["quote"]["exact"] == long_text[:200] over = _anchor(state, nid, span=[0, 201]) assert over["quote"]["length"] == 201 assert over["quote"]["exact_hash"] == hashing.PLAIN(norm(long_text[:201])) def test_a_cell_anchor_carries_the_table_label_and_header_paths(self): state = package_state(HALE) doc = state.doc() cell = next( n for n in ids_of_kind(doc, "cell") if hashing.plain(doc, n) == "310.0" ) a = _anchor(state, cell, store="smithlab") assert a["context"] == { "table_label": "Table 1", "row_path": ["Bond parameters", "CT\N{EN DASH}CT"], "column_path": ["Set A", "$K_r$ (kcal mol⁻¹ Å⁻²)"], } assert a["quote"] == {"exact": "310.0"} def test_a_container_with_content_has_no_quote_and_no_leaves(self, tree): a = _anchor(tree["state"], tree["section"]) assert a["kind"] == "section" assert not {"quote", "leaves", "span", "context"} & set(a) def test_a_container_without_content_lists_its_leaves_with_their_match_hashes( self, tree ): state = tree["state"] values = hashing.compute(state.doc()) a = _anchor(state, tree["p1"]) assert a["leaves"] == [ [tree["s1"], values[tree["s1"]]["match_hash"]], [tree["s2"], values[tree["s2"]]["match_hash"]], ] assert "quote" not in a def test_the_whole_document_is_a_container_without_content(self, tree): state = tree["state"] a = _anchor(state, state.doc().root) assert len(a["leaves"]) == 5 class TestResolveAllNodes: @pytest.mark.parametrize("package", [HALE, "fixtures/packages/tiny2026tiny-j4qm"]) def test_an_anchor_on_any_node_of_the_unchanged_document_is_current(self, package): state = package_state(package) doc = state.doc() values = hashing.compute(doc) for nid in doc.order: a = anchors.make_anchor(doc, values, nid, state.rev) got = anchors.resolve(state, a) assert got == { "result": "current", "node": nid, "node_hash": values[nid]["node_hash"], } def test_a_span_anchor_on_any_leaf_is_current_with_its_span(self): state = package_state(HALE) doc = state.doc() values = hashing.compute(doc) for nid in doc.order: if doc.nodes[nid]["kind"] not in LEAVES: continue size = len(hashing.plain(doc, nid)) span = [size // 3, size // 3 + size // 4] a = anchors.make_anchor(doc, values, nid, state.rev, span) got = anchors.resolve(state, a) assert got["result"] == "current" assert got["span"] == span # --- resolution --------------------------------------------------------------------- @pytest.mark.parametrize("case", vectors("resolve")) def test_resolve_vector(case): state = package_state(case["package"]) assert anchors.resolve(state, case["anchor"]) == case["expect"] def test_the_vectors_reach_all_five_results(): results = {c["expect"]["result"] for c in read_cases("resolve")} assert results == {"current", "changed-below", "moved", "reattached", "stale"} class TestResolveLeaf: def test_an_edit_that_keeps_the_quote_once_reattaches_the_anchor(self, tree): anchor = _anchor(tree["state"], tree["s1"]) later = _edit(tree["state"], {tree["s1"]: FIRST + " It holds widely."}) got = anchors.resolve(later, anchor) assert got["result"] == "reattached" assert got["node"] == tree["s1"] assert "span" not in got def test_a_reattached_span_anchor_reports_the_new_span(self, tree): start = FIRST.index("covalent") anchor = _anchor(tree["state"], tree["s1"], span=[start, start + 8]) later = _edit(tree["state"], {tree["s1"]: "Indeed, " + FIRST}) assert anchors.resolve(later, anchor) == { "result": "reattached", "node": tree["s1"], "node_hash": hashing.compute(later.doc())[tree["s1"]]["node_hash"], "span": [start + 8, start + 16], } def test_an_edit_that_removes_the_quote_makes_the_anchor_stale(self, tree): anchor = _anchor(tree["state"], tree["s1"]) later = _edit(tree["state"], {tree["s1"]: "Something else entirely."}) got = anchors.resolve(later, anchor) assert got["result"] == "stale" assert ( got["reason"] == "the node changed and the quote does not occur exactly once" ) assert got["node"] == tree["s1"] def test_a_quote_without_context_that_occurs_twice_is_stale(self, tree): text = "The cat sat. The cat ran." base = _edit(tree["state"], {tree["s1"]: text}) start = text.rindex("cat") anchor = _anchor(base, tree["s1"], span=[start, start + 3]) anchor["quote"] = {"exact": "cat"} got = anchors.resolve(_edit(base, {tree["s1"]: text + " More."}), anchor) assert got["result"] == "stale" def test_the_prefix_and_suffix_pick_one_of_several_occurrences(self, tree): lead = "Start of the sentence runs on for quite some while here. " text = lead + "The cat sat down. The cat ran off home." base = _edit(tree["state"], {tree["s1"]: text}) start = text.rindex("cat") anchor = _anchor(base, tree["s1"], span=[start, start + 3]) changed = _edit(base, {tree["s1"]: text.replace("Start", "Begin")}) got = anchors.resolve(changed, anchor) assert got["result"] == "reattached" assert got["span"] == [start, start + 3] def test_a_long_quote_is_found_again_by_its_hash(self, tree): body = " ".join(f"word{i}" for i in range(60)) base = _edit(tree["state"], {tree["s1"]: "Lead. " + body + " Tail."}) anchor = _anchor(base, tree["s1"], span=[6, 6 + len(body)]) assert "exact_hash" in anchor["quote"] got = anchors.resolve( _edit(base, {tree["s1"]: "New lead. " + body + " Tail."}), anchor ) assert got["result"] == "reattached" assert got["span"] == [10, 10 + len(body)] def test_an_anchor_without_a_kind_takes_the_kind_of_the_live_node(self, tree): anchor = _anchor(tree["state"], tree["s1"]) del anchor["kind"] assert anchors.resolve(tree["state"], anchor)["result"] == "current" def test_an_anchor_without_a_quote_on_a_changed_leaf_is_stale(self, tree): anchor = _anchor(tree["state"], tree["s1"]) del anchor["quote"] later = _edit(tree["state"], {tree["s1"]: "Changed."}) assert anchors.resolve(later, anchor)["result"] == "stale" class TestIdentifiersThatMoved: def test_an_unknown_node_is_stale(self, tree): anchor = dict(_anchor(tree["state"], tree["s1"]), node="zzzzzzz") assert anchors.resolve(tree["state"], anchor) == { "result": "stale", "node": None, "reason": "unknown node", } def test_a_retired_node_without_a_successor_is_stale(self, tree): anchor = _anchor(tree["state"], tree["s1"]) gone = _edit( tree["state"], {}, drop={tree["s1"]}, ids=[{"id": tree["s1"], "kind": "retired", "node_kind": "sentence"}], ) assert anchors.resolve(gone, anchor) == { "result": "stale", "node": None, "via": [tree["s1"]], "reason": "retired without a successor", } def test_a_chain_of_aliases_that_loops_is_stale(self, tree): anchor = dict(_anchor(tree["state"], tree["s1"]), node="aaaaaaa") ids = [ {"id": "aaaaaaa", "kind": "alias", "successor": "bbbbbbb"}, {"id": "bbbbbbb", "kind": "alias", "successor": "aaaaaaa"}, ] got = anchors.resolve(_edit(tree["state"], {}, ids=ids), anchor) assert got["result"] == "stale" assert got["via"] == ["aaaaaaa", "bbbbbbb"] assert got["reason"] == "retired without a successor" def test_an_alias_is_followed_and_reported(self, tree): anchor = dict(_anchor(tree["state"], tree["s1"]), node="aaaaaaa") ids = [{"id": "aaaaaaa", "kind": "alias", "successor": tree["s1"]}] got = anchors.resolve(_edit(tree["state"], {}, ids=ids), anchor) assert got["result"] == "current" assert got["node"] == tree["s1"] assert got["via"] == ["aaaaaaa"] def test_a_retired_leaf_moves_to_a_successor_that_holds_the_quote(self, tree): anchor = _anchor(tree["state"], tree["s1"]) ids = [ { "id": tree["s1"], "kind": "retired", "node_kind": "sentence", "successor": tree["s2"], } ] later = _edit( tree["state"], {tree["s2"]: SECOND + " " + FIRST}, drop={tree["s1"]}, ids=ids, ) got = anchors.resolve(later, anchor) assert got["result"] == "moved" assert got["node"] == tree["s2"] assert got["via"] == [tree["s1"]] def test_a_moved_span_anchor_reports_where_the_span_went(self, tree): start = FIRST.index("common") anchor = _anchor(tree["state"], tree["s1"], span=[start, start + 6]) ids = [ { "id": tree["s1"], "kind": "retired", "node_kind": "sentence", "successor": tree["s2"], } ] successor = "Before. " + FIRST later = _edit( tree["state"], {tree["s2"]: successor}, drop={tree["s1"]}, ids=ids ) got = anchors.resolve(later, anchor) assert got["result"] == "moved" assert got["span"] == [start + 8, start + 14] def test_a_retired_leaf_whose_successor_lacks_the_quote_is_stale(self, tree): anchor = _anchor(tree["state"], tree["s1"]) ids = [ { "id": tree["s1"], "kind": "retired", "node_kind": "sentence", "successor": tree["s2"], } ] later = _edit(tree["state"], {}, drop={tree["s1"]}, ids=ids) got = anchors.resolve(later, anchor) assert got["result"] == "stale" assert got["reason"] == "the successor does not contain the quote" assert got["node"] == tree["s2"] def test_a_retired_span_anchor_needs_exactly_one_hit(self, tree): start = 4 anchor = _anchor(tree["state"], tree["s1"], span=[start, start + 4]) quote = anchor["quote"]["exact"] ids = [ { "id": tree["s1"], "kind": "retired", "node_kind": "sentence", "successor": tree["s2"], } ] twice = _edit( tree["state"], {tree["s2"]: f"{quote} and {quote}"}, drop={tree["s1"]}, ids=ids, ) anchor["quote"] = {"exact": quote} assert anchors.resolve(twice, anchor)["result"] == "stale" whole = dict(anchor) del whole["span"] assert anchors.resolve(twice, whole)["result"] == "moved" def test_the_kind_comes_from_the_retired_entry_when_the_anchor_has_none(self, tree): anchor = _anchor(tree["state"], tree["p1"]) del anchor["kind"] ids = [ { "id": tree["p1"], "kind": "retired", "node_kind": "paragraph", "successor": tree["p2"], } ] later = _edit( tree["state"], {}, drop={tree["p1"], tree["s2"]}, ids=ids, move=(tree["s1"], tree["p2"], 5), ) assert anchors.resolve(later, anchor)["result"] == "moved" class TestResolveContainers: def test_a_section_whose_leaves_changed_is_changed_below_with_its_drift(self, tree): anchor = _anchor(tree["state"], tree["section"]) correction = { "index": 1, "op": "replace", "path": [tree["section"]], "touched": [tree["s1"]], } later = _edit( tree["state"], {tree["s1"]: "Changed text."}, corrections=[correction] ) got = anchors.resolve(later, anchor) assert got["result"] == "changed-below" assert got["drift"] == {"count": 1, "share": "0.2000", "level": "low"} def test_drift_is_high_when_the_touched_share_passes_the_threshold(self, tree): anchor = _anchor(tree["state"], tree["section"]) corrections = [ { "index": 1, "path": [tree["section"]], "touched": [tree["s1"], tree["s2"]], }, { "index": 2, "to_path": [tree["section"]], "touched": [tree["s2"], tree["s3"]], }, {"index": 3, "path": ["other"], "touched": [tree["s4"]]}, {"index": 4, "path": [tree["section"]], "touched": []}, ] later = _edit( tree["state"], {tree["s1"]: "x one", tree["s3"]: "y two"}, corrections=corrections, ) got = anchors.resolve(later, anchor) assert got["drift"] == {"count": 2, "share": "0.6000", "level": "high"} def test_corrections_before_the_anchor_do_not_count(self, tree): anchor = _anchor(tree["state"], tree["section"], rev=2) corrections = [ {"index": 1, "path": [tree["section"]], "touched": [tree["s1"]]}, {"index": 2, "path": [tree["section"]], "touched": [tree["s2"]]}, {"index": 3, "path": [tree["section"]], "touched": [tree["s3"]]}, ] later = _edit(tree["state"], {tree["s3"]: "z"}, corrections=corrections) assert anchors.resolve(later, anchor)["drift"]["count"] == 1 def test_the_threshold_can_be_given(self, tree): anchor = _anchor(tree["state"], tree["section"]) corrections = [{"index": 1, "path": [tree["section"]], "touched": [tree["s1"]]}] later = _edit(tree["state"], {tree["s1"]: "x"}, corrections=corrections) assert anchors.resolve(later, anchor)["drift"]["level"] == "low" assert ( anchors.resolve(later, anchor, threshold=Fraction(1, 10))["drift"]["level"] == "high" ) assert ( anchors.resolve(later, anchor, threshold=Fraction(1, 5))["drift"]["level"] == "low" ) @pytest.mark.parametrize( ("touched", "share"), [ (["s1"], "0.5000"), (["s1", "s2", "gone"], "1.0000"), (["s1", "gone"], "0.6667"), (["gone"], "0.3333"), ], ) def test_a_share_is_written_with_four_places_rounded_half_up( self, tree, touched, share ): anchor = _anchor(tree["state"], tree["p1"]) ids = [tree.get(t, t) for t in touched] corrections = [{"index": 1, "path": [tree["p1"]], "touched": ids}] later = _edit(tree["state"], {tree["s1"]: "changed"}, corrections=corrections) assert anchors.resolve(later, anchor)["drift"]["share"] == share def test_drift_is_none_when_no_correction_touched_the_node(self, tree): anchor = _anchor(tree["state"], tree["p1"]) later = _edit(tree["state"], {tree["s1"]: "changed"}) assert anchors.resolve(later, anchor)["drift"] == { "count": 0, "share": "0.0000", "level": "none", } def test_a_section_whose_own_content_changed_is_stale(self, tree): anchor = _anchor(tree["state"], tree["section"]) nodes = [ dict(n, label="2") if n["id"] == tree["section"] else n for n in tree["state"].nodes ] later = State(tree["state"].key, nodes) got = anchors.resolve(later, anchor) assert got["result"] == "stale" assert got["reason"] == "the node's own content changed" def test_a_relabel_alone_reattaches_the_anchor(self, tree): anchor = _anchor(tree["state"], tree["section"]) nodes = [ dict(n, label="2") if n["id"] == tree["section"] else n for n in tree["state"].nodes ] relabel = { "index": 1, "op": "relabel", "target": tree["section"], "from": "1", "to": "2", } got = anchors.resolve( State(tree["state"].key, nodes, corrections=[relabel]), anchor ) assert got["result"] == "reattached" assert got["reason"] == "relabel" def test_a_relabel_beside_another_change_to_the_node_does_not_reattach(self, tree): anchor = _anchor(tree["state"], tree["section"]) nodes = [ dict(n, label="2") if n["id"] == tree["section"] else n for n in tree["state"].nodes ] other = { "index": 2, "op": "replace", "path": [tree["section"]], "touched": [tree["s1"]], } relabel = {"index": 1, "op": "relabel", "target": tree["section"], "from": "1"} got = anchors.resolve( State(tree["state"].key, nodes, corrections=[relabel, other]), anchor ) assert got["result"] == "stale" def test_a_relabel_to_a_different_original_label_is_stale(self, tree): anchor = _anchor(tree["state"], tree["section"]) nodes = [ dict(n, label="3") if n["id"] == tree["section"] else n for n in tree["state"].nodes ] relabel = { "index": 1, "op": "relabel", "target": tree["section"], "from": "2", "to": "3", } assert ( anchors.resolve( State(tree["state"].key, nodes, corrections=[relabel]), anchor )["result"] == "stale" ) def test_a_paragraph_is_current_or_changed_below(self, tree): anchor = _anchor(tree["state"], tree["p1"]) assert anchors.resolve(tree["state"], anchor)["result"] == "current" later = _edit(tree["state"], {tree["s1"]: "changed"}) assert anchors.resolve(later, anchor)["result"] == "changed-below" def test_a_retired_section_with_the_same_own_content_moved(self, tree): anchor = _anchor(tree["state"], tree["section"]) successor = dict(tree["state"].doc().nodes[tree["section"]], id="sec2222") nodes = [ dict(n, parent="sec2222") if n.get("parent") == tree["section"] else n for n in tree["state"].nodes ] nodes = [n for n in nodes if n["id"] != tree["section"]] nodes.insert(1, successor) ids = [ { "id": tree["section"], "kind": "retired", "node_kind": "section", "successor": "sec2222", } ] got = anchors.resolve(State(tree["state"].key, nodes, ids), anchor) assert got["result"] == "moved" assert got["node"] == "sec2222" def test_a_retired_section_with_different_own_content_is_stale(self, tree): anchor = _anchor(tree["state"], tree["section"]) successor = dict( tree["state"].doc().nodes[tree["section"]], id="sec2222", label="9" ) nodes = [ dict(n, parent="sec2222") if n.get("parent") == tree["section"] else n for n in tree["state"].nodes ] nodes = [n for n in nodes if n["id"] != tree["section"]] nodes.insert(1, successor) ids = [ { "id": tree["section"], "kind": "retired", "node_kind": "section", "successor": "sec2222", } ] got = anchors.resolve(State(tree["state"].key, nodes, ids), anchor) assert got["result"] == "stale" assert got["reason"] == "the node's own content changed" def test_a_retired_paragraph_moves_when_half_its_leaves_are_held(self, tree): anchor = _anchor(tree["state"], tree["p1"]) ids = [ { "id": tree["p1"], "kind": "retired", "node_kind": "paragraph", "successor": tree["p2"], } ] later = _edit( tree["state"], {}, drop={tree["p1"], tree["s2"]}, ids=ids, move=(tree["s1"], tree["p2"], 5), ) got = anchors.resolve(later, anchor) assert got["result"] == "moved" assert got["node"] == tree["p2"] def test_a_retired_paragraph_holds_a_leaf_that_was_rewritten_with_the_same_match_hash( self, tree ): anchor = _anchor(tree["state"], tree["p1"]) ids = [ { "id": tree["p1"], "kind": "retired", "node_kind": "paragraph", "successor": tree["p2"], } ] later = _edit( tree["state"], {tree["s3"]: FIRST}, drop={tree["p1"], tree["s1"], tree["s2"]}, ids=ids, ) assert anchors.resolve(later, anchor)["result"] == "moved" def test_a_retired_paragraph_is_stale_when_fewer_than_half_its_leaves_are_held( self, tree ): anchor = _anchor(tree["state"], tree["p1"]) ids = [ { "id": tree["p1"], "kind": "retired", "node_kind": "paragraph", "successor": tree["p2"], } ] later = _edit( tree["state"], {}, drop={tree["p1"], tree["s1"], tree["s2"]}, ids=ids ) got = anchors.resolve(later, anchor) assert got["result"] == "stale" assert ( got["reason"] == "the successor holds fewer than half of the original leaves" ) # --- following IDs and resolving addresses ------------------------------------------ KEY = "hale2026harmonic-damb" def _jsonl(name): """The records of `nodes.jsonl` or `ids.jsonl` of the Hale package, as stored.""" path = ROOT / HALE / f"{name}.jsonl" return [json.loads(line) for line in path.read_text("utf-8").splitlines()] class TestFollow: def test_follow_is_the_old_private_name(self): assert anchors._follow is anchors.follow def test_a_live_node_is_followed_to_itself(self, tree): assert anchors.follow(tree["state"], tree["s1"]) == (tree["s1"], [], None) def test_an_alias_gives_a_chain_and_the_alias_kind(self, tree): ids = [{"id": "aaaaaaa", "kind": "alias", "successor": tree["s1"]}] got = anchors.follow(_edit(tree["state"], {}, ids=ids), "aaaaaaa") assert got == (tree["s1"], ["aaaaaaa"], "alias") def test_a_retirement_makes_the_chain_retired_even_after_an_alias(self, tree): ids = [ {"id": "aaaaaaa", "kind": "alias", "successor": "bbbbbbb"}, {"id": "bbbbbbb", "kind": "retired", "successor": tree["s1"]}, ] got = anchors.follow(_edit(tree["state"], {}, ids=ids), "aaaaaaa") assert got == (tree["s1"], ["aaaaaaa", "bbbbbbb"], "retired") def test_a_deletion_ends_the_chain_without_a_node(self, tree): ids = [{"id": "ddddddd", "kind": "retired", "successor": None}] got = anchors.follow(_edit(tree["state"], {}, ids=ids), "ddddddd") assert got == (None, ["ddddddd"], "retired") def test_an_unknown_id_gives_no_node_and_no_chain(self, tree): assert anchors.follow(tree["state"], "zzzzzzz") == (None, [], None) class TestResolveAddress: @pytest.fixture def hale(self): nodes = _jsonl("nodes") sentence_id = next(n["id"] for n in nodes if n["kind"] == "sentence") return { "nodes": nodes, "ids": _jsonl("ids"), "sid": sentence_id, "hash": next(n["node_hash"] for n in nodes if n["id"] == sentence_id), } def _resolve(self, hale, tail, **kw): return anchors.resolve_address( hale["nodes"], hale["ids"], f"{KEY}#{tail}", **kw ) def test_an_unpinned_address_of_a_live_node_is_current(self, hale): assert self._resolve(hale, hale["sid"]) == { "result": "current", "node": hale["sid"], "node_hash": hale["hash"], } def test_a_pin_that_starts_the_node_hash_is_current(self, hale): got = self._resolve(hale, f"{hale['sid']}@{hale['hash'][:6]}") assert got["result"] == "current" def test_a_pin_that_differs_is_stale(self, hale): other = "000000" if not hale["hash"].startswith("000000") else "ffffff" got = self._resolve(hale, f"{hale['sid']}@{other}") assert got["result"] == "stale" assert got["reason"] == "the pin differs from the node hash" assert got["node"] == hale["sid"] def test_a_span_is_carried_to_a_current_result(self, hale): got = self._resolve(hale, f"{hale['sid']}@{hale['hash'][:6]}[3:9]") assert got["span"] == [3, 9] def test_an_empty_span_is_a_valid_address_and_resolves(self, hale): assert anchors.parse_address(f"{KEY}#{hale['sid']}[4:4]")["span"] == [4, 4] assert self._resolve(hale, f"{hale['sid']}[4:4]")["span"] == [4, 4] def test_a_reversed_span_is_not_an_address(self, hale): assert self._resolve(hale, f"{hale['sid']}[9:3]") == { "result": "stale", "node": None, "reason": "not an address", } def test_the_grammar_takes_any_node_part_so_a_short_one_parses(self): assert anchors.parse_address(f"{KEY}#n1")["node"] == "n1" def test_an_alias_is_followed_and_its_pin_judged(self, hale): node = next(n for n in hale["nodes"] if n["id"] == "hca6dc5") got = self._resolve(hale, f"b-p01-text-003@{node['node_hash'][:6]}") assert got == { "result": "current", "node": "hca6dc5", "node_hash": node["node_hash"], "via": ["b-p01-text-003"], } def test_a_retirement_with_a_successor_is_stale_and_names_the_successor(self, hale): got = self._resolve(hale, "ayea71r") assert got["result"] == "stale" assert got["reason"] == "retired" assert got["node"] == "xjns57z" assert got["via"] == ["ayea71r"] def test_a_deletion_is_stale_without_a_node(self, hale): assert self._resolve(hale, "v8e4z6z") == { "result": "stale", "node": None, "via": ["v8e4z6z"], "reason": "retired without a successor", } def test_an_unknown_node_is_stale(self, hale): assert self._resolve(hale, "zzzzzzz") == { "result": "stale", "node": None, "reason": "unknown node", } def test_text_that_is_not_an_address_is_stale(self, hale): got = anchors.resolve_address(hale["nodes"], hale["ids"], "nonsense") assert got["reason"] == "not an address" def test_given_values_replace_the_stored_node_hash(self, hale): values = {hale["sid"]: {"node_hash": "abcdef" + "0" * 58}} got = self._resolve(hale, f"{hale['sid']}@abcdef", values=values) assert got["result"] == "current" assert got["node_hash"] == "abcdef" + "0" * 58 assert ( self._resolve(hale, f"{hale['sid']}@{hale['hash'][:6]}", values=values)[ "result" ] == "stale" ) def test_a_node_without_a_hash_fails_a_pin_but_not_an_unpinned_address(self): nodes = [{"id": "n1"}] assert anchors.resolve_address(nodes, [], f"{KEY}#n1@abcdef")["result"] == ( "stale" ) assert anchors.resolve_address(nodes, [], f"{KEY}#n1")["result"] == "current" def test_it_agrees_with_resolve_on_every_node_of_the_unchanged_document(self): nodes, ids = _jsonl("nodes"), _jsonl("ids") for n in nodes: got = anchors.resolve_address( nodes, ids, f"{KEY}#{n['id']}@{n['node_hash'][:6]}" ) assert got["result"] == "current" assert got["node"] == n["id"]