okf-wiki/tests/test_audit.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

1048 lines
52 KiB
Python

"""Tests for okfwiki/audit.py, the auditor. One test class per check, and the known-positive must stay clean.
Every fixture here is synthetic and neutral text about baking bread (CLAUDE.md rule 3: nothing derived from
Anthropic documentation is committed). The gate's real cases live in gates-local/.
The main-page rule (contract K2, wave 2 order 7) runs only when the sources root holds a K1 file
(source-manifest.json): `Fixture` has none and checks what audit() gives without it, `K2Fixture` writes one.
Run: python3 -m unittest discover -s tests
"""
from __future__ import annotations
import hashlib
import json
import subprocess
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.audit import ( # noqa: E402
Finding,
K1Error,
audit,
link_rule_report,
load_bundle,
main_page_report,
read_k1,
sentence_spans,
sentences,
)
from okfwiki.klink import reduce_links # 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.
See [crust notes](/nowhere.md) for the long version.
"""
SOURDOUGH = """---
type: Concept
title: Sourdough
description: A bread raised by a starter.
tags: [bread, starter]
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: b-5
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 5 }
x-quote: 'See [crust notes](/nowhere.md) for the long version.'
x-main-for:
- /kilde/bread.md
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-27T09:00:00Z }
---
# Sourdough
**Short:** Sourdough needs a starter that is fed every day.[^b-2] The dough rests for twelve hours, e.g. overnight,
before it is baked.[^b-3]
## Steps
- Feed the starter each day.[^b-2]
- Rest the dough (see `rest.time`) for twelve hours.[^b-3] The source points to longer notes.[^b-5]
## Related
- [Crust](crust.md)
[^b-2]: Bread notes, line 2
[^b-3]: Bread notes, line 3
[^b-5]: Bread notes, line 5
"""
CRUST = """---
type: Concept
title: Crust
description: The outer layer of a baked loaf.
sources:
- id: b-4
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 4 }
x-quote: 'A hot oven gives a dark crust.'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-27T09:00:00Z }
---
# Crust
A hot oven gives a dark crust, as with [sourdough](sourdough.md).[^b-4] The notes say the same about any
loaf, see [a guide](https://example.org/bread.html).[^b-4]
[^b-4]: Bread notes, line 4
"""
INDEX = """# Bread
* [Sourdough](sourdough.md) - A bread raised by a starter.
* [Crust](crust.md) - The outer layer of a baked loaf.
"""
LOG = """# Directory Update Log
## 2026-09-27
* **Creation**: Added [Crust](crust.md).
## 2026-09-25
* **Creation**: Added [Sourdough](sourdough.md).
"""
BASE = {"sourdough.md": SOURDOUGH, "crust.md": CRUST, "index.md": INDEX, "log.md": LOG}
Edit = tuple[str, str] | str | None
class Fixture(unittest.TestCase):
"""Writes the known-positive bundle and its raw source, applies edits, and runs the auditor."""
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory(prefix="audit-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.bundle = self.root / "bundle"
self.bundle.mkdir()
def tearDown(self) -> None:
self._tmp.cleanup()
def write(self, edits: dict[str, Edit] | None = None) -> Path:
"""Each edit is (old, new) replaced once and required to match, a full new text, or None to delete."""
files = dict(BASE)
for name, edit in (edits or {}).items():
if edit is None:
files.pop(name)
elif isinstance(edit, tuple):
old, new = edit
self.assertIn(old, files[name], f"edit does not match {name}")
files[name] = files[name].replace(old, new, 1)
else:
files[name] = edit
for name, text in files.items():
p = self.bundle / name
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text(text, encoding="utf-8")
return self.bundle
def findings(self, edits: dict[str, Edit] | None = None) -> list[Finding]:
return audit(self.write(edits), self.sources)
def checks(self, edits: dict[str, Edit] | None = None) -> set[str]:
return {f.check for f in self.findings(edits)}
def assertOnly(self, check: str, edits: dict[str, Edit]) -> None:
self.assertEqual({check}, self.checks(edits))
class KnownPositive(Fixture):
def test_clean(self) -> None:
self.assertEqual([], self.findings())
class UncitedSentence(Fixture):
def test_sentence_appended_to_a_cited_paragraph(self) -> None:
self.assertOnly("uncited-sentence", {"crust.md": (
"loaf, see [a guide](https://example.org/bread.html).[^b-4]",
"loaf, see [a guide](https://example.org/bread.html).[^b-4] It also smells good.")})
def test_list_item_without_footnote(self) -> None:
self.assertOnly("uncited-sentence", {"sourdough.md": ("- Feed the starter each day.[^b-2]\n",
"- Feed the starter each day.[^b-2]\n- Salt helps.\n")})
def test_second_sentence_in_a_list_item_without_footnote(self) -> None:
self.assertOnly("uncited-sentence", {"sourdough.md": ("for twelve hours.[^b-3] The source points to longer notes.[^b-5]",
"for twelve hours.[^b-3] The source points to longer notes.")})
def test_uncited_sentence_is_reported_at_its_line(self) -> None:
found = self.findings({"sourdough.md": ("## Related\n", "Salt helps.\n\n## Related\n")})
self.assertEqual(["uncited-sentence"], [f.check for f in found])
text = (self.bundle / "sourdough.md").read_text(encoding="utf-8").splitlines()
line = found[0].line
assert line is not None
self.assertEqual("Salt helps.", text[line - 1])
def test_a_link_after_an_abbreviation_leaves_a_cited_sentence_cited(self) -> None:
# The link pass places a link whose anchor starts right after "U.S. ": the sentence stays one, with its footnote.
self.assertEqual([], self.findings({"crust.md": (
"A hot oven gives a dark crust, as with [sourdough](sourdough.md).[^b-4]",
"A hot oven gives a dark crust, as in U.S. [sourdough](sourdough.md) baking.[^b-4]")}))
def test_headings_link_lists_abbreviations_and_code_spans_are_not_uncited_sentences(self) -> None:
# The known-positive has all four: headings, a pure link list, "e.g." and a code span with a period.
self.assertNotIn("uncited-sentence", self.checks())
class QuoteNotVerbatim(Fixture):
def test_one_word_changed(self) -> None:
self.assertOnly("quote-not-verbatim", {"crust.md": ("'A hot oven gives a dark crust.'",
"'A hot oven makes a dark crust.'")})
class QuoteWrongLocator(Fixture):
def test_right_text_on_another_line(self) -> None:
self.assertOnly("quote-wrong-locator", {"crust.md": ("x-locator: { line: 4 }", "x-locator: { line: 3 }")})
def test_line_beyond_the_end_of_the_source(self) -> None:
self.assertOnly("quote-wrong-locator", {"crust.md": ("x-locator: { line: 4 }", "x-locator: { line: 400 }")})
class QuoteMissing(Fixture):
def test_source_without_x_quote(self) -> None:
self.assertOnly("quote-missing", {"crust.md": (" x-quote: 'A hot oven gives a dark crust.'\n", "")})
def test_empty_x_quote(self) -> None:
self.assertOnly("quote-missing", {"crust.md": ("'A hot oven gives a dark crust.'", "''")})
class LocatorUnsupported(Fixture):
def test_locator_missing(self) -> None:
self.assertOnly("locator-unsupported", {"crust.md": (" x-locator: { line: 4 }\n", "")})
def test_locator_with_another_key(self) -> None:
self.assertOnly("locator-unsupported", {"crust.md": ("x-locator: { line: 4 }", "x-locator: { page: 4 }")})
def test_line_zero_or_not_an_integer(self) -> None:
for value in ("0", "'4'", "true"):
with self.subTest(value=value):
self.assertOnly("locator-unsupported", {"crust.md": ("x-locator: { line: 4 }", f"x-locator: {{ line: {value} }}")})
class SourceUnreadable(Fixture):
def findings_for(self, resource: str) -> list[Finding]:
return self.findings({"crust.md": (" resource: /kilde/bread.md\n", f" resource: {resource}\n")})
def test_a_url_is_not_a_raw_source_path(self) -> None:
self.assertEqual(["source-unreadable"], [f.check for f in self.findings_for("https://example.org/bread.md")])
def test_a_missing_file(self) -> None:
self.assertEqual(["source-unreadable"], [f.check for f in self.findings_for("/kilde/rye.md")])
def test_a_file_that_is_not_utf8(self) -> None:
(self.sources / "kilde" / "latin.md").write_bytes("A hot oven gives a dark crust. \xe6\xf8\xe5\n".encode("latin-1"))
self.assertEqual(["source-unreadable"], [f.check for f in self.findings_for("/kilde/latin.md")])
def test_a_resource_that_leaves_the_raw_source_root_is_not_read(self) -> None:
# The file outside the root holds the quote on line 1, so only the containment guard can stop it.
(self.root / "outside.md").write_text("A hot oven gives a dark crust.\n", encoding="utf-8")
for resource in ("/../outside.md", "/kilde/../../outside.md", "/%2e%2e/outside.md"):
with self.subTest(resource=resource):
found = self.findings({"crust.md": CRUST.replace(
" resource: /kilde/bread.md\n", f" resource: {resource}\n", 1).replace(
"x-locator: { line: 4 }", "x-locator: { line: 1 }", 1)})
self.assertEqual(["source-unreadable"], [f.check for f in found])
self.assertIn("leaves the raw-source root", found[0].message)
class SourceMissingId(Fixture):
def test_entry_without_id(self) -> None:
# The footnote [^b-4] then names no source, so footnote-unknown-id is expected alongside.
checks = self.checks({"crust.md": (" - id: b-4\n resource:", " - resource:")})
self.assertIn("source-missing-id", checks)
self.assertLessEqual(checks, {"source-missing-id", "footnote-unknown-id"})
class SourceDuplicateId(Fixture):
def test_id_used_twice(self) -> None:
extra = (" - id: b-2\n resource: /kilde/bread.md\n x-locator: { line: 3 }\n"
" x-quote: 'The dough rests for twelve hours'\n")
self.assertOnly("source-duplicate-id", {"sourdough.md": (" - id: b-3\n", extra + " - id: b-3\n")})
class FootnoteUnknownId(Fixture):
def test_footnote_label_with_no_source(self) -> None:
self.assertOnly("footnote-unknown-id", {"crust.md": (
"dark crust, as with [sourdough](sourdough.md).[^b-4]",
"dark crust, as with [sourdough](sourdough.md).[^b-4][^b-9]")})
def test_definition_with_no_source(self) -> None:
self.assertOnly("footnote-unknown-id", {"crust.md": ("[^b-4]: Bread notes, line 4\n",
"[^b-4]: Bread notes, line 4\n[^b-9]: Bread notes, line 9\n")})
class ResourceNotBundleAbsolute(Fixture):
def test_path_without_leading_slash(self) -> None:
# SPEC 6.2 still resolves it relative to the file, so the quote itself verifies.
self.assertOnly("resource-not-bundle-absolute", {"crust.md": ("resource: /kilde/bread.md", "resource: kilde/bread.md")})
class BodyLinkBundleAbsolute(Fixture):
def test_body_link_with_leading_slash(self) -> None:
self.assertOnly("body-link-bundle-absolute", {"sourdough.md": ("- [Crust](crust.md)", "- [Crust](/crust.md)")})
class VerifiedNotHuman(Fixture):
def test_process_actor(self) -> None:
self.assertOnly("verified-not-human", {"crust.md": (
"---\n\n# Crust", "verified: { by: process:nightly, at: 2026-09-27T10:00:00Z }\n---\n\n# Crust")})
def test_list_with_one_process_actor(self) -> None:
self.assertOnly("verified-not-human", {"crust.md": (
"---\n\n# Crust",
"verified:\n - { by: human:baker, at: 2026-09-27T10:00:00Z }\n"
" - { by: claude-code/claude-opus-5-5, at: 2026-09-27T11:00:00Z }\n---\n\n# Crust")})
def test_human_actor_is_clean(self) -> None:
self.assertEqual(set(), self.checks({"crust.md": (
"---\n\n# Crust", "verified: { by: human:baker, at: 2026-09-27T10:00:00Z }\n---\n\n# Crust")}))
class Spec11Frontmatter(Fixture):
def test_unparseable_yaml(self) -> None:
self.assertOnly("spec11-1-frontmatter", {"sourdough.md": ("tags: [bread, starter]", "tags: [bread, starter")})
def test_file_without_frontmatter(self) -> None:
self.assertOnly("spec11-1-frontmatter", {
"notes.md": "# Notes\n",
"sourdough.md": ("- [Crust](crust.md)\n", "- [Crust](crust.md)\n- [Notes](notes.md)\n"), # an inbound link (criterion 6)
"index.md": (INDEX, INDEX + "* [Notes](notes.md) - Drafts.\n")})
def test_unterminated_frontmatter(self) -> None:
self.assertIn("spec11-1-frontmatter", self.checks({"crust.md": ("---\n\n# Crust", "\n# Crust")}))
def test_frontmatter_in_a_subdirectory(self) -> None:
self.assertIn("spec11-1-frontmatter", self.checks({
"more/rye.md": "# Rye\n", "more/index.md": "# More\n\n* [Rye](rye.md) - Rye bread.\n",
"index.md": (INDEX, INDEX + "* [More](more/) - More breads.\n")}))
class Spec11Type(Fixture):
def test_type_missing(self) -> None:
self.assertOnly("spec11-2-type", {"crust.md": ("type: Concept\n", "")})
def test_type_empty(self) -> None:
self.assertOnly("spec11-2-type", {"crust.md": ("type: Concept\n", "type: ''\n")})
class Spec11Index(Fixture):
def test_index_with_frontmatter(self) -> None:
self.assertOnly("spec11-3-index", {"index.md": "---\ntype: Index\n---\n" + INDEX})
def test_index_without_heading(self) -> None:
self.assertOnly("spec11-3-index", {"index.md": ("# Bread\n\n", "")})
def test_root_index_with_okf_version_only_is_clean(self) -> None:
self.assertEqual(set(), self.checks({"index.md": "---\nokf_version: '0.2'\n---\n" + INDEX}))
class Spec11Log(Fixture):
def test_date_heading_not_iso(self) -> None:
self.assertOnly("spec11-3-log", {"log.md": ("## 2026-09-25", "## 25.09.2026")})
def test_oldest_first(self) -> None:
self.assertOnly("spec11-3-log", {"log.md": LOG.replace("2026-09-27", "X").replace("2026-09-25", "2026-09-27")
.replace("X", "2026-09-25")})
class TimestampForm(Fixture):
def test_space_separated_generated_at(self) -> None:
self.assertOnly("timestamp-form", {"crust.md": ("at: 2026-09-27T09:00:00Z", "at: 2026-09-27 09:00:00+00:00")})
def test_no_utc_offset(self) -> None:
self.assertOnly("timestamp-form", {"crust.md": ("at: 2026-09-27T09:00:00Z", "at: 2026-09-27T09:00:00")})
class BrokenLink(Fixture):
def test_link_list_entry_to_a_missing_page(self) -> None:
self.assertOnly("broken-link", {"sourdough.md": ("- [Crust](crust.md)\n", "- [Crust](crust.md)\n- [Rye](rye.md)\n")})
def test_inline_link_to_a_missing_page(self) -> None:
self.assertOnly("broken-link", {"sourdough.md": ("- Feed the starter each day.",
"- Feed the [starter](starter.md) each day.")})
def test_link_inside_a_frontmatter_value_is_not_a_body_link(self) -> None:
# The known-positive quotes a source line that holds a link to a file that does not exist.
self.assertNotIn("broken-link", self.checks())
def test_link_inside_a_code_span_is_misplaced_not_broken(self) -> None:
self.assertOnly("link-misplaced", {"sourdough.md": ("(see `rest.time`)", "(see `[x](missing.md)`)")})
class OrphanPage(Fixture):
def test_page_no_concept_and_no_index_links_to(self) -> None:
# log.md still links to crust.md: the log is history, not navigation, so crust.md is an orphan.
# An orphan is by definition also absent from the index, so index-coverage is expected alongside.
checks = self.checks({
"sourdough.md": ("## Related\n- [Crust](crust.md)\n\n", ""),
"index.md": ("* [Crust](crust.md) - The outer layer of a baked loaf.\n", "")})
self.assertIn("orphan-page", checks)
self.assertLessEqual(checks, {"orphan-page", "index-coverage"})
RYE = """---
type: Concept
title: Rye
description: A dense bread.
sources:
- id: b-3
resource: /kilde/bread.md
title: Bread notes
x-locator: { line: 3 }
x-quote: 'The dough rests for twelve hours'
generated: { by: claude-code/claude-opus-5-5, at: 2026-09-27T09:00:00Z }
---
# Rye
Rye dough also rests for twelve hours.[^b-3]
[^b-3]: Bread notes, line 3
"""
RELATED = "- [Crust](crust.md)\n"
class LinkRuleFixture(Fixture):
def report(self, edits: dict[str, Edit] | None = None) -> dict[str, object]:
return link_rule_report(load_bundle(self.write(edits), self.sources))
def line_of(self, name: str, needle: str) -> int:
lines = (self.bundle / name).read_text(encoding="utf-8").split("\n")
return next(i for i, line in enumerate(lines, 1) if needle in line)
def without_related(self, old: str, new: str) -> str:
"""SOURDOUGH with its link-list line to crust.md removed and one more edit, so crust.md loses that inbound link."""
self.assertIn(old, SOURDOUGH)
return SOURDOUGH.replace(RELATED, "", 1).replace(old, new, 1)
class LinkRule(LinkRuleFixture):
"""The rule of 04.10.2026 (an inbound link from another concept page's body) as numbers. Wave 2 order 7 retires
it as a finding (`link-rule`); link_rule_report keeps its form, because the linker and the trial still count it."""
def test_page_linked_only_from_index_and_log_is_counted_not_found(self) -> None:
edits: dict[str, Edit] = {"sourdough.md": (RELATED, "")}
self.assertEqual([], self.findings(edits))
self.assertEqual((1, 2), (self.report(edits)["pass"], self.report(edits)["of"]))
def test_a_self_link_does_not_count(self) -> None:
edits: dict[str, Edit] = {"sourdough.md": (RELATED, ""),
"crust.md": ("A hot oven gives a dark crust,", "A hot oven gives a dark [crust](crust.md),")}
self.assertEqual([], self.findings(edits))
self.assertEqual((1, 2), (self.report(edits)["pass"], self.report(edits)["of"]))
def test_a_link_list_line_counts(self) -> None:
# crust.md's only inbound link from a concept is the link-list line under Related in sourdough.md.
self.assertEqual([], self.findings())
self.assertEqual((2, 2), (self.report()["pass"], self.report()["of"]))
def test_inbound_only_in_code_heading_or_footnote_is_misplaced_and_not_counted(self) -> None:
cases = {
"code": ("(see `rest.time`)", "(see `[crust](crust.md)`)"),
"heading": ("## Steps\n", "## Steps for [Crust](crust.md)\n"),
"footnote": ("[^b-5]: Bread notes, line 5", "[^b-5]: Bread notes, line 5, see [Crust](crust.md)"),
}
for place, (old, new) in cases.items():
with self.subTest(place=place):
edits: dict[str, Edit] = {"sourdough.md": self.without_related(old, new)}
self.assertEqual({"link-misplaced"}, self.checks(edits))
self.assertEqual(1, self.report(edits)["pass"])
def test_reserved_files_are_not_in_the_denominator(self) -> None:
self.assertEqual(2, self.report()["of"])
def test_pages_in_subdirectories_count(self) -> None:
found = self.findings({"sub/rye.md": RYE})
self.assertEqual({("orphan-page", "sub/rye.md")}, {(f.check, f.file) for f in found})
linked: dict[str, Edit] = {"sub/rye.md": RYE, "sourdough.md": (RELATED, RELATED + "- [Rye](sub/rye.md)\n")}
self.assertEqual([], self.findings(linked))
self.assertEqual((3, 3), (self.report(linked)["pass"], self.report(linked)["of"]))
def test_the_key_reports_n_of_n_on_the_known_positive(self) -> None:
report = self.report()
self.assertEqual("link rule: 2 of 2 concept pages have an inbound link", report["line"])
self.assertEqual((0, 0, 0, 1), (report["misplaced"], report["broken"], report["not_to_concept"], report["max_out_degree"]))
def test_an_empty_bundle_without_k1_has_no_finding_and_reports_0_of_0(self) -> None:
self.assertEqual([], audit(self.bundle, self.sources))
self.assertEqual((0, 0), (link_rule_report(load_bundle(self.bundle, self.sources))["pass"],
link_rule_report(load_bundle(self.bundle, self.sources))["of"]))
def test_link_rule_is_never_a_finding(self) -> None:
# Without K1 the K2 classes do not run either (K2 point 18): only today's other checks.
edits: dict[str, Edit] = {"sourdough.md": (RELATED, ""),
"crust.md": ("as with [sourdough](sourdough.md).", "as with sourdough.")}
self.assertEqual([], self.findings(edits))
self.assertEqual((0, 2), (self.report(edits)["pass"], self.report(edits)["of"]))
def test_provenance_marks_are_counted_not_checked(self) -> None:
edits: dict[str, Edit] = {"crust.md": (" x-quote: 'A hot oven gives a dark crust.'\n",
" x-quote: 'A hot oven gives a dark crust.'\n x-provenance: documented\n")}
self.assertEqual([], self.findings(edits))
self.assertEqual({"documented": 1, "missing": 3}, self.report(edits)["provenance"])
class LinkMisplaced(LinkRuleFixture):
"""Criterion 6 (b): no link to a bundle file sits in code, a heading or a footnote definition."""
def assertMisplacedAt(self, edits: dict[str, Edit], needle: str) -> None:
found = self.findings(edits)
self.assertIn(("link-misplaced", "sourdough.md", self.line_of("sourdough.md", needle)),
[(f.check, f.file, f.line) for f in found])
def test_inline_code(self) -> None:
self.assertMisplacedAt({"sourdough.md": ("(see `rest.time`)", "(see `[crust](crust.md)`)")}, "`[crust](crust.md)`")
def test_fenced_block(self) -> None:
fence = RELATED + "\n```\n[the crust](crust.md)\n```\n"
self.assertMisplacedAt({"sourdough.md": (RELATED, fence)}, "[the crust](crust.md)")
def test_heading(self) -> None:
self.assertMisplacedAt({"sourdough.md": ("## Steps\n", "## Steps for [Crust](crust.md)\n")}, "## Steps for")
def test_footnote_definition(self) -> None:
self.assertMisplacedAt({"sourdough.md": ("[^b-5]: Bread notes, line 5", "[^b-5]: Bread notes, line 5, see [Crust](crust.md)")},
"[^b-5]: Bread notes, line 5, see")
def test_a_link_inside_a_frontmatter_quote_is_not_misplaced(self) -> None:
self.assertNotIn("link-misplaced", self.checks())
def test_a_link_whose_anchor_is_code_is_in_prose(self) -> None:
# The code sits inside the anchor text; the link itself stands in the sentence and counts as inbound.
edits: dict[str, Edit] = {"sourdough.md": self.without_related("(see `rest.time`)", "(see [`crust`](crust.md))")}
self.assertEqual([], self.findings(edits))
def test_a_bracket_in_a_code_span_before_a_link_opens_no_link(self) -> None:
# A code span binds before a link (CommonMark 6.1): its [ is text, so the link after it stands in the sentence.
edits: dict[str, Edit] = {"sourdough.md": self.without_related("(see `rest.time`)", "(press `[` or see [crust](crust.md))")}
self.assertEqual([], self.findings(edits))
def test_an_external_link_in_code_is_not_misplaced(self) -> None:
self.assertEqual(set(), self.checks({"sourdough.md": ("(see `rest.time`)", "(see `[a](https://example.org/a.html)`)")}))
class LinesAfterAFence(LinkRuleFixture):
"""A finding below a fenced block is reported at its own file line (the fence's line breaks are counted)."""
FENCE = "## Steps\n\n```\nmix\nknead\nbake\n```\n"
def at(self, edits: dict[str, Edit], check: str) -> list[tuple[str, int | None]]:
return [(f.file, f.line) for f in self.findings(edits) if f.check == check]
def test_a_broken_link_after_a_fenced_block(self) -> None:
edits: dict[str, Edit] = {"sourdough.md": SOURDOUGH.replace("## Steps\n", self.FENCE, 1).replace(
"- Feed the starter each day.", "- Feed the [starter](starter.md) each day.", 1)}
found = self.at(edits, "broken-link")
self.assertEqual([("sourdough.md", self.line_of("sourdough.md", "[starter](starter.md)"))], found)
def test_a_footnote_with_no_source_after_a_fenced_block(self) -> None:
edits: dict[str, Edit] = {"sourdough.md": SOURDOUGH.replace("## Steps\n", self.FENCE, 1).replace(
"- Feed the starter each day.[^b-2]", "- Feed the starter each day.[^b-2][^b-9]", 1)}
found = self.at(edits, "footnote-unknown-id")
self.assertEqual([("sourdough.md", self.line_of("sourdough.md", "[^b-9]"))], found)
class CodeSpanStaysInItsBlock(LinkRuleFixture):
"""A code span never pairs a backtick with one in a later block, and an escaped backtick opens none (CommonMark
6.1): text between an unpaired backtick and the next block's backtick is prose, so its links count."""
LINK = ("- Feed the starter each day.", "- Feed the [crust](crust.md) starter each day.")
def edits(self, tick: str, link: tuple[str, str] = LINK) -> dict[str, Edit]:
text = SOURDOUGH.replace("fed every day.[^b-2]", f"fed every day ({tick} key).[^b-2]", 1)
return {"sourdough.md": text.replace(*link, 1)}
def test_an_unpaired_backtick_leaves_a_link_in_a_later_block_in_prose(self) -> None:
self.assertEqual([], self.findings(self.edits("one `")))
def test_an_escaped_backtick_opens_no_code_span(self) -> None:
self.assertEqual([], self.findings(self.edits("the \\`")))
def test_a_broken_link_after_an_unpaired_backtick_is_found(self) -> None:
link = ("- Feed the starter each day.", "- Feed the [rye](rye.md) starter each day.")
self.assertEqual({"broken-link"}, self.checks(self.edits("one `", link)))
def test_a_code_span_inside_one_paragraph_still_masks(self) -> None:
self.assertEqual({"link-misplaced"}, self.checks(self.edits("a `[crust](crust.md)`")) - {"uncited-sentence"})
class NotToConcept(LinkRuleFixture):
def test_links_to_index_and_log_are_counted_not_found(self) -> None:
edits: dict[str, Edit] = {"crust.md": ("as with [sourdough](sourdough.md).",
"as with [sourdough](sourdough.md), [the index](index.md) and [the log](log.md).")}
self.assertEqual([], self.findings(edits))
self.assertEqual(2, self.report(edits)["not_to_concept"])
def test_an_external_link_is_neither(self) -> None:
# crust.md links to https://example.org/bread.html.
self.assertEqual(0, self.report()["not_to_concept"])
class IndexCoverage(Fixture):
def test_linked_page_missing_from_the_index(self) -> None:
self.assertOnly("index-coverage", {"index.md": ("* [Crust](crust.md) - The outer layer of a baked loaf.\n", "")})
def test_index_line_with_no_file(self) -> None:
self.assertOnly("index-coverage", {"index.md": (INDEX, INDEX + "* [Rye](rye.md) - Rye bread.\n")})
RELEASE = """## 1.2.3
- Added a rye setting to the oven
"""
K2_CLASSES = ("main-page-missing", "main-page-duplicate", "main-page-invalid", "no-main-page-link", "link-misplaced")
def k1_entry(path: str, text: str, kind: str, main_topic: bool) -> dict[str, Any]:
data = text.encode("utf-8")
entry: dict[str, Any] = {"bytes": len(data), "kind": kind, "lines": len(text.splitlines()), "main_topic": main_topic,
"path": path, "sha256": hashlib.sha256(data).hexdigest(),
"url": "https://example.org/" + path.removeprefix("kilde/")}
if kind == "release-notes":
entry["version"] = "1.2.3"
return entry
def k1_text(sources: list[dict[str, Any]]) -> str:
doc = {"collection": "bread", "frozen_at": "2026-10-08T12:00:00Z", "schema": "okf-wiki/source-manifest/1",
"sources": sources, "subset_of": None}
return json.dumps(doc, indent=1, sort_keys=True, ensure_ascii=False) + "\n"
# Crust also cites the release note (in K1, not a main topic), so a mark on it can be tested.
CRUST_RELEASE = (" - id: b-4\n", " - id: r-2\n resource: /kilde/release-v1.2.3.md\n title: Release notes\n"
" x-locator: { line: 2 }\n x-quote: 'Added a rye setting to the oven'\n - id: b-4\n")
MAIN_FOR = "x-main-for:\n - /kilde/bread.md\n"
class K2Fixture(Fixture):
"""The known-positive under K2: K1 lists bread.md (docs, a main topic) and a release note (not one).
sourdough.md is the main page of bread.md; crust.md is a non-main page linked from sourdough's Related list."""
def setUp(self) -> None:
super().setUp()
(self.sources / "kilde" / "release-v1.2.3.md").write_text(RELEASE, encoding="utf-8")
self.k1 = self.sources / "source-manifest.json"
self.k1.write_text(k1_text([k1_entry("kilde/bread.md", SOURCE, "docs", True),
k1_entry("kilde/release-v1.2.3.md", RELEASE, "release-notes", False)]),
encoding="utf-8")
def k2(self, edits: dict[str, Edit] | None = None) -> list[tuple[str, str]]:
"""(check, file) of the K2 classes and link-misplaced, sorted."""
return sorted((f.check, f.file) for f in self.findings(edits) if f.check in K2_CLASSES)
def main_for(self, value: str) -> dict[str, Edit]:
"""sourdough.md with its x-main-for block replaced by `x-main-for: <value>` (YAML flow or block text)."""
return {"sourdough.md": (MAIN_FOR, f"x-main-for: {value}\n")}
def related(self, new: str) -> dict[str, Edit]:
"""sourdough.md with its one link to crust.md (the Related list line) replaced."""
return {"sourdough.md": (RELATED, new)}
NO_MAIN_PAGE = [("main-page-missing", "kilde/bread.md"), ("no-main-page-link", "crust.md"),
("no-main-page-link", "sourdough.md")]
class MainPageRule(K2Fixture):
"""K2 points 1-5: every main-topic source has exactly one main page; every other page a link from one."""
def test_the_known_positive_is_clean(self) -> None:
self.assertEqual([], self.findings())
def test_a_main_page_needs_no_inbound_link(self) -> None:
self.assertEqual([], self.findings({"crust.md": ("as with [sourdough](sourdough.md).", "as with sourdough.")}))
def test_the_retired_inbound_rule_is_not_a_finding(self) -> None:
self.assertNotIn("link-rule", {f.check for f in self.findings({"crust.md": (
"as with [sourdough](sourdough.md).", "as with sourdough.")})})
def test_main_page_missing(self) -> None:
found = [f for f in self.findings({"sourdough.md": (MAIN_FOR, "")}) if f.check == "main-page-missing"]
self.assertEqual(NO_MAIN_PAGE, self.k2({"sourdough.md": (MAIN_FOR, "")}))
self.assertIn("/kilde/bread.md", found[0].message)
def test_main_page_duplicate(self) -> None:
self.assertEqual([("main-page-duplicate", "kilde/bread.md")],
self.k2({"crust.md": ("generated:", MAIN_FOR + "generated:")}))
def test_main_page_invalid_value_not_among_the_page_sources(self) -> None:
self.assertEqual([("main-page-invalid", "crust.md")],
self.k2({"crust.md": ("generated:", "x-main-for:\n - /kilde/oven.md\ngenerated:")}))
def test_main_page_invalid_release_note(self) -> None:
edits: dict[str, Edit] = {"crust.md": CRUST_RELEASE}
self.assertEqual([], self.findings(edits))
marked = CRUST.replace(*CRUST_RELEASE).replace("generated:", "x-main-for:\n - /kilde/release-v1.2.3.md\ngenerated:")
self.assertEqual([("main-page-invalid", "crust.md")], self.k2({"crust.md": marked}))
def test_links_from_index_log_itself_or_a_non_main_page_do_not_count(self) -> None:
rye_linked_from_crust = ("as with [sourdough](sourdough.md).", "as with [sourdough](sourdough.md) and [rye](rye.md).")
cases: dict[str, dict[str, Edit]] = {
"index and log": {"sourdough.md": (RELATED, "")},
"itself": {"sourdough.md": (RELATED, ""),
"crust.md": ("A hot oven gives a dark crust,", "A hot oven gives a dark [crust](crust.md),")},
"a non-main page": {"rye.md": RYE, "crust.md": rye_linked_from_crust,
"index.md": (INDEX, INDEX + "* [Rye](rye.md) - A dense bread.\n")},
}
expected = {"index and log": [("no-main-page-link", "crust.md")],
"itself": [("no-main-page-link", "crust.md")],
"a non-main page": [("no-main-page-link", "rye.md")]}
for name, edits in cases.items():
with self.subTest(case=name):
self.assertEqual(expected[name], self.k2(edits))
def test_pages_in_subdirectories_count(self) -> None:
linked: dict[str, Edit] = {"sub/rye.md": RYE, "sourdough.md": (RELATED, RELATED + "- [Rye](sub/rye.md)\n")}
self.assertEqual([], self.findings(linked))
self.assertEqual([("no-main-page-link", "sub/rye.md")], self.k2({"sub/rye.md": RYE}))
class MainPageMarkValues(K2Fixture):
"""K2 points 10-13: how each x-main-for value is judged."""
def test_point_10_each_list_item_is_judged_alone(self) -> None:
found = self.findings(self.main_for("[/kilde/bread.md, 7, null]"))
self.assertEqual([("main-page-invalid", "sourdough.md")] * 2, [(f.check, f.file) for f in found])
def test_point_10_a_value_that_is_not_a_list_gives_one_finding_and_no_role(self) -> None:
for value in ("/kilde/bread.md", "{a: /kilde/bread.md}", "null", "7"):
with self.subTest(value=value):
self.assertEqual(sorted([("main-page-invalid", "sourdough.md")] + NO_MAIN_PAGE),
self.k2(self.main_for(value)))
def test_point_11_an_empty_list_gives_one_finding_and_no_role(self) -> None:
self.assertEqual(sorted([("main-page-invalid", "sourdough.md")] + NO_MAIN_PAGE), self.k2(self.main_for("[]")))
def test_point_12_the_same_value_twice_counts_once_and_gives_one_finding(self) -> None:
self.assertEqual([("main-page-invalid", "sourdough.md")],
self.k2(self.main_for("[/kilde/bread.md, /kilde/bread.md]")))
def test_point_13_the_comparison_is_an_exact_string(self) -> None:
for value in ("[/kilde/Bread.md]", "[kilde/bread.md]", "[/kilde/./bread.md]", "['/kilde/bread.md ']"):
with self.subTest(value=value):
self.assertEqual(sorted([("main-page-invalid", "sourdough.md")] + NO_MAIN_PAGE),
self.k2(self.main_for(value)))
def test_point_13_a_value_matching_a_resource_without_its_slash_is_not_a_k1_path(self) -> None:
edits: dict[str, Edit] = {"sourdough.md": SOURDOUGH.replace("resource: /kilde/bread.md", "resource: kilde/bread.md")
.replace(MAIN_FOR, "x-main-for: [kilde/bread.md]\n")}
self.assertEqual(sorted([("main-page-invalid", "sourdough.md")] + NO_MAIN_PAGE), self.k2(edits))
class MainPageLinks(K2Fixture):
"""K2 points 14 and 15 and the cases the mutant gate does not try: which links from a main page count."""
def test_point_14_inline_relative_links_count_wherever_they_stand_in_the_body(self) -> None:
cases = {
"an anchor": "- [Crust](crust.md#top)\n",
"a dot path": "- [Crust](./crust.md)\n",
"a sentence": "Feed it, then see [the crust](crust.md).[^b-2]\n",
"a table cell": "| Part | Note |\n| --- | --- |\n| Crust | See [the crust](crust.md).[^b-2] |\n",
"a quote block": "> See [the crust](crust.md).[^b-2]\n",
"a nested list": "- Parts\n - [Crust](crust.md)\n",
}
for name, new in cases.items():
with self.subTest(case=name):
self.assertEqual([], self.k2(self.related(new)))
def test_point_14_reference_links_and_autolinks_do_not_count(self) -> None:
cases = {
"a reference link": "- [Crust][c]\n\n[c]: crust.md\n",
"an autolink": "- <crust.md>\n",
}
for name, new in cases.items():
with self.subTest(case=name):
self.assertEqual([("no-main-page-link", "crust.md")], self.k2(self.related(new)))
def test_point_14_links_in_code_headings_and_footnote_definitions_do_not_count(self) -> None:
cases = {
"inline code": ("(see `rest.time`)", "(see `[crust](crust.md)`)"),
"a backtick fence": ("## Related\n", "## Related\n\n```\n[Crust](crust.md)\n```\n\n"),
"a tilde fence": ("## Related\n", "## Related\n\n~~~\n[Crust](crust.md)\n~~~\n\n"),
"a tilde fence in a list item": ("- Feed the starter each day.[^b-2]\n",
"- Feed the starter each day.[^b-2]\n\n ~~~\n [Crust](crust.md)\n ~~~\n\n"),
"a tilde fence in a quote block": ("## Related\n", "## Related\n\n> ~~~\n> [Crust](crust.md)\n> ~~~\n\n"),
"a heading": ("## Steps\n", "## Steps for [Crust](crust.md)\n"),
"a footnote definition": ("[^b-5]: Bread notes, line 5", "[^b-5]: Bread notes, line 5, see [Crust](crust.md)"),
}
for name, (old, new) in cases.items():
with self.subTest(case=name):
text = SOURDOUGH.replace(RELATED, "", 1)
self.assertIn(old, text)
self.assertEqual([("link-misplaced", "sourdough.md"), ("no-main-page-link", "crust.md")],
self.k2({"sourdough.md": text.replace(old, new, 1)}))
def test_point_15_a_link_starting_with_a_slash_does_not_count(self) -> None:
found = self.findings(self.related("- [Crust](/crust.md)\n"))
self.assertIn(("body-link-bundle-absolute", "sourdough.md"), [(f.check, f.file) for f in found])
self.assertEqual([("no-main-page-link", "crust.md")], self.k2(self.related("- [Crust](/crust.md)\n")))
def test_point_16_a_main_page_whose_frontmatter_does_not_parse_has_no_role(self) -> None:
found = self.findings({"sourdough.md": ("tags: [bread, starter]", "tags: [bread, starter")})
self.assertEqual(sorted([("spec11-1-frontmatter", "sourdough.md")] + NO_MAIN_PAGE),
sorted((f.check, f.file) for f in found))
class K1File(K2Fixture):
"""K2 points 6 and 18: the rule runs only on a valid K1 file at the sources root, read by the auditor itself."""
INVALID = {
"not JSON": "{",
"not an object": "[]\n",
"another schema": k1_text([]).replace("okf-wiki/source-manifest/1", "okf-wiki/source-manifest/2"),
"sources not a list": k1_text([]).replace('"sources": []', '"sources": {}'),
"an entry that is not an object": k1_text([]).replace('"sources": []', '"sources": ["kilde/bread.md"]'),
"an entry without path": k1_text([]).replace('"sources": []', '"sources": [{"main_topic": true}]'),
"a path that is not a string": k1_text([]).replace('"sources": []', '"sources": [{"main_topic": true, "path": 7}]'),
"an entry without main_topic": k1_text([]).replace('"sources": []', '"sources": [{"path": "kilde/bread.md"}]'),
"a main_topic that is not a boolean": k1_text([]).replace(
'"sources": []', '"sources": [{"main_topic": "true", "path": "kilde/bread.md"}]'),
}
def test_read_k1_gives_the_main_topic_per_path(self) -> None:
self.assertEqual({"kilde/bread.md": True, "kilde/release-v1.2.3.md": False}, read_k1(self.sources))
def test_read_k1_without_the_file_is_none(self) -> None:
self.k1.unlink()
self.assertIsNone(read_k1(self.sources))
def test_an_invalid_k1_file_raises(self) -> None:
for name, text in self.INVALID.items():
with self.subTest(case=name):
self.k1.write_text(text, encoding="utf-8")
with self.assertRaises(K1Error):
read_k1(self.sources)
with self.assertRaises(K1Error):
audit(self.write(), self.sources)
def test_audit_without_k1_gives_no_k2_class(self) -> None:
self.k1.unlink()
self.assertEqual([], self.findings({"sourdough.md": (MAIN_FOR, "x-main-for: 7\n")}))
def test_the_auditor_does_not_import_the_k1_module(self) -> None:
source = (ROOT / "okfwiki" / "audit.py").read_text(encoding="utf-8")
self.assertNotIn("okfwiki.sources", source)
self.assertNotIn("from okfwiki import sources", source)
class MainPageReport(K2Fixture):
"""K2 point 7: the report line, N of N main-topic sources with exactly one main page and N of N non-main pages."""
def report(self, edits: dict[str, Edit] | None = None) -> dict[str, Any]:
bundle = self.write(edits)
k1 = read_k1(self.sources)
assert k1 is not None
return main_page_report(load_bundle(bundle, self.sources), k1)
def test_the_known_positive(self) -> None:
report = self.report()
self.assertEqual("main pages: 1 of 1 sources · linked from a main page: 1 of 1 pages", report["line"])
self.assertEqual({"pass": 1, "of": 1}, report["main_pages"])
self.assertEqual({"pass": 1, "of": 1}, report["linked"])
self.assertEqual((0, 0, 0, 1), (report["misplaced"], report["broken"], report["not_to_concept"], report["max_out_degree"]))
def test_a_source_with_no_main_page_and_its_pages(self) -> None:
self.assertEqual("main pages: 0 of 1 sources · linked from a main page: 0 of 2 pages",
self.report({"sourdough.md": (MAIN_FOR, "")})["line"])
def test_a_source_with_two_main_pages_is_not_counted(self) -> None:
self.assertEqual("main pages: 0 of 1 sources · linked from a main page: 0 of 0 pages",
self.report({"crust.md": ("generated:", MAIN_FOR + "generated:")})["line"])
class CommandLine(K2Fixture):
def run_cli(self, *args: str) -> subprocess.CompletedProcess[str]:
return subprocess.run([sys.executable, "-m", "okfwiki.audit", *args], cwd=ROOT,
capture_output=True, text=True, check=False)
def test_clean_bundle_exits_0_with_no_findings(self) -> None:
proc = self.run_cli(str(self.write()), str(self.sources))
self.assertEqual(0, proc.returncode, proc.stderr)
self.assertEqual([], json.loads(proc.stdout)["findings"])
def test_alarm_exits_1_and_reports_links_and_spec11_separately(self) -> None:
bundle = self.write({"crust.md": ("type: Concept\n", ""),
"sourdough.md": ("- [Crust](crust.md)\n", "- [Crust](crust.md)\n- [Rye](rye.md)\n")})
proc = self.run_cli(str(bundle), str(self.sources))
self.assertEqual(1, proc.returncode, proc.stderr)
payload = json.loads(proc.stdout)
groups = {f["check"]: f["group"] for f in payload["findings"]}
self.assertEqual({"spec11-2-type": "spec-11", "broken-link": "links"}, groups)
self.assertEqual(1, payload["summary"]["spec-11"])
self.assertEqual(1, payload["summary"]["links"])
def test_k2_classes_are_in_the_links_group(self) -> None:
proc = self.run_cli(str(self.write({"sourdough.md": (MAIN_FOR, "")})), str(self.sources))
self.assertEqual(1, proc.returncode, proc.stderr)
payload = json.loads(proc.stdout)
self.assertEqual({"main-page-missing": "links", "no-main-page-link": "links"},
{f["check"]: f["group"] for f in payload["findings"]})
self.assertEqual(3, payload["summary"]["links"])
def test_stdout_is_one_json_object_with_the_main_page_report(self) -> None:
proc = self.run_cli(str(self.write()), str(self.sources))
payload = json.loads(proc.stdout)
self.assertEqual({"findings", "summary", "link_rule"}, set(payload))
self.assertEqual({"spec-11": 0, "links": 0, "citations": 0, "format": 0}, payload["summary"])
self.assertEqual("main pages: 1 of 1 sources · linked from a main page: 1 of 1 pages", payload["link_rule"]["line"])
self.assertEqual(({"pass": 1, "of": 1}, {"pass": 1, "of": 1}),
(payload["link_rule"]["main_pages"], payload["link_rule"]["linked"]))
def test_link_rule_counts_broken_links(self) -> None:
bundle = self.write({"sourdough.md": ("- [Crust](crust.md)\n", "- [Crust](crust.md)\n- [Rye](rye.md)\n")})
proc = self.run_cli(str(bundle), str(self.sources))
self.assertEqual(1, json.loads(proc.stdout)["link_rule"]["broken"])
def test_two_runs_give_identical_bytes(self) -> None:
bundle = self.write({"sourdough.md": (MAIN_FOR, "")})
first, second = self.run_cli(str(bundle), str(self.sources)), self.run_cli(str(bundle), str(self.sources))
self.assertEqual((first.returncode, first.stdout), (second.returncode, second.stdout))
def test_missing_bundle_exits_2(self) -> None:
proc = self.run_cli(str(self.root / "nope"), str(self.sources))
self.assertEqual(2, proc.returncode)
def test_without_k1_the_command_exits_2_never_0(self) -> None:
self.k1.unlink()
proc = self.run_cli(str(self.write()), str(self.sources))
self.assertEqual(2, proc.returncode, proc.stdout)
self.assertEqual("", proc.stdout)
self.assertIn("source-manifest.json", proc.stderr)
def test_no_main_topic_source_and_no_concept_page_is_no_denominator_and_exits_2(self) -> None:
self.k1.write_text(k1_text([k1_entry("kilde/release-v1.2.3.md", RELEASE, "release-notes", False)]), encoding="utf-8")
proc = self.run_cli(str(self.bundle), str(self.sources)) # the bundle folder is still empty
self.assertEqual(2, proc.returncode, proc.stdout)
self.assertIn("denominator", proc.stderr)
proc = self.run_cli(str(self.write()), str(self.sources)) # pages, but no main page can exist: every page fails
self.assertEqual(1, proc.returncode, proc.stderr)
self.assertEqual({"no-main-page-link", "main-page-invalid"},
{f["check"] for f in json.loads(proc.stdout)["findings"]})
def test_an_invalid_k1_file_exits_2(self) -> None:
for name, text in K1File.INVALID.items():
with self.subTest(case=name):
self.k1.write_text(text, encoding="utf-8")
proc = self.run_cli(str(self.write()), str(self.sources))
self.assertEqual(2, proc.returncode, proc.stdout)
self.assertEqual("", proc.stdout)
class SentenceTest(unittest.TestCase):
"""A period after a common abbreviation ends no sentence, whatever follows it; any other period before a capital
or a digit still does."""
def count(self, text: str) -> int:
return len(sentences(text))
def test_norwegian_abbreviations_keep_their_sentence(self) -> None:
self.assertEqual(self.count("Bruk f.eks. Oslo som eksempel.[^a] Neste setning.[^b]"), 2)
self.assertEqual(self.count("Møtet starter kl. 14 i dag.[^a]"), 1)
self.assertEqual(self.count("Se bl.a. Ole Brumm og ca. 200 andre (jf. Kap. 3).[^a]"), 1)
self.assertEqual(self.count("Kl. 9 åpner kontoret.[^a]"), 1)
def test_english_abbreviations_keep_their_sentence(self) -> None:
self.assertEqual(self.count("Use a tool, e.g. Claude Code, for this.[^a]"), 1)
self.assertEqual(self.count("Ask Dr. Smith, i.e. The Expert.[^a]"), 1)
def test_other_periods_still_end_a_sentence(self) -> None:
self.assertEqual(self.count("Den er ferdig. Neste del.[^a]"), 2)
self.assertEqual(self.count("Det skjedde i 2022. 300 kom.[^a]"), 2)
self.assertEqual(self.count("Epler, pærer osv. Neste setning.[^a]"), 2)
# a single capital before the period is an initial: the name goes on (measured on a real PDF, 07.11)
self.assertEqual(self.count("It is presented by Steven L. Rickman of NASA.[^a]"), 1)
# an abbreviation is written in lower case or with a capital first letter; "MRs" is a word of its own
self.assertEqual(self.count("Results go back via MRs. GitLab listens.[^a]"), 2)
class SentenceLinkTest(unittest.TestCase):
"""A bundle link placed on an anchor never changes where a text splits into sentences: the cuts are those of the
same text with every bundle link reduced to its anchor text (klink's notion of a link), mapped back to the
linked text. The character after a period that decides "sentence end or not" is the anchor's first letter."""
def reduced(self, text: str) -> str:
return reduce_links(text)[0]
def assertSplitsAsLinkFree(self, text: str) -> None:
plain = self.reduced(text)
self.assertNotEqual(plain, text, "the case must hold a bundle link")
linked = [self.reduced(text[a:b]) for a, b in sentence_spans(text)]
self.assertEqual([plain[a:b] for a, b in sentence_spans(plain)], linked, text)
def test_a_link_after_us_keeps_the_sentence_whole(self) -> None:
# The real case (a folder build, pack 25): the link pass placed this link and the build stopped.
plain = "U.S. primary aluminum production was 889 in 2021, compared with 1,012 in 2020.[^s1]"
linked = ("U.S. [primary aluminum production](primary-aluminum.md) was 889 in 2021, compared with 1,012 in"
" 2020.[^s1]")
self.assertEqual([(0, len(plain))], sentence_spans(plain))
self.assertEqual([(0, len(linked))], sentence_spans(linked))
self.assertEqual([linked], sentences(linked))
def test_a_link_after_each_protected_abbreviation(self) -> None:
for text in [
"U.S. [primary aluminum production](primary-aluminum.md) was 889 in 2021.[^s1]",
"Use a tool, e.g. [Claude Code](claude-code.md), for this.[^a]",
"Use a tool, e.g. [overnight rest](rest.md), for this.[^a]",
"Ask Dr. Smith, i.e. [The Expert](expert.md).[^a]",
"Ask [Dr. Smith](smith.md), i.e. the expert.[^a]",
"It is presented by Steven L. [Rickman](rickman.md) of NASA.[^a]",
"Bruk f.eks. [Oslo](oslo.md) som eksempel.[^a] Neste setning.[^b]",
"Møtet starter kl. [14](tid.md) i dag.[^a]",
"Se bl.a. [Ole Brumm](ole-brumm.md) og ca. [200 andre](andre.md) (jf. [Kap. 3](kap-3.md)).[^a]",
"Epler, pærer osv. [neste ting](ting.md) kom.[^a] Ny setning.[^b]",
"Read [the guide.](guide.md) Then rest.[^a]",
]:
with self.subTest(text=text):
self.assertSplitsAsLinkFree(text)
def test_link_free_text_splits_as_before(self) -> None:
# Pinned spans of the splitter before links were reduced: klink's sentence keys rest on them.
for text, spans in [
("U.S. primary aluminum production was 889 in 2021, compared with 1,012 in 2020.[^s1]", [(0, 83)]),
("It ended. Next began.[^a]", [(0, 9), (10, 25)]),
("Read the guide. Then rest.[^a]", [(0, 15), (16, 30)]),
("Epler, pærer osv. neste ting.[^a] Ny.[^b]", [(0, 33), (34, 41)]),
("Done (see `a. B`). Next one.[^a][^b] Third? Yes! ", [(0, 18), (19, 36), (37, 43), (44, 48)]),
("Bruk f.eks. Oslo som eksempel.[^a] Neste setning.[^b]", [(0, 34), (35, 53)]),
# an external link is no bundle link: klink keeps it, so the splitter reads it as before
("See U.S. [policy](https://example.org/p) here.[^a]", [(0, 8), (9, 50)]),
]:
with self.subTest(text=text):
self.assertEqual(spans, sentence_spans(text))
def test_a_real_end_before_a_link_still_cuts(self) -> None:
self.assertEqual(2, len(sentence_spans("It ended. Next began.[^a]")))
self.assertEqual(["It ended.", "[Next](x.md) began.[^a]"], sentences("It ended. [Next](x.md) began.[^a]"))
self.assertSplitsAsLinkFree("It ended. [Next](x.md) began.[^a]")
def test_a_link_in_code_is_not_reduced(self) -> None:
text = "Run `U.S. [x](y.md)` now. Then stop.[^a]"
self.assertEqual([(0, 25), (26, 40)], sentence_spans(text))
if __name__ == "__main__":
unittest.main()