Files
paperspec/tests/test_anchors.py
T
alexmandClaude 4fb8b4f5a7 Add paperspec correct, check math forms and datasets, and give the tools public names
The work the other paper tools planned for paperspec (paperdesk PLAN M5.4,
paperform PLAN 4.2):

- paperspec correct and paperspec.revision apply proposed corrections to a
  package, folder or zip, and write it only once it validates.
- doc.math.form is checked: label and style commands always, the form's own
  spelling when papermath is installed or forms= is passed.
- paperspec.datasets and seven doc.dataset.* rules check a package's datasets.
- fixtures/invalid gains suspect-witness and math-form-label (33 in all).
- Canonical JSON reads numbers as doubles, so 1e20 round-trips.
- The registries and the JSON-LD context ship in the wheel.
- Public names for what paperdesk and paperform imported as private ones,
  with the old names kept as aliases.
- The text and lossy-projection functions are about three times faster
  through the gate, tested equal to the old code on every code point.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013XwDhn4LkrKQfw4ArDEr2E
2026-10-20 22:10:17 -04:00

983 lines
35 KiB
Python

# 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"]