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>
1048 lines
52 KiB
Python
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()
|