fix(okf): the index entry point never requires 'type', frontmatter or not

navigate_bundle died on an index.md that carried a frontmatter block without
a 'type' field: _parse_index_entry keyed its tolerance on the ABSENCE of the
block, so a frontmatter-ful index fell through to parse_concept_file and
raised. Not merely the index read failed — the whole navigation did.

OKF v0.2 (A-E6) triggers this: it stamps okf_version into index.md. Our own
assumption ("a generated index has no frontmatter") is frozen in the golden,
so nothing caught it. The defect is ours, not theirs.

method-spec §3 Step 1 renders the index as "the index body (the summary)"
and every OTHER file as a "non-index concept file" — the index is not a
concept file, so the 'type' requirement never reached it in the first place.
The tolerance is now keyed on being the index, which is what it always meant.

Load-bearing, both directions detach-proved:
- test_index_with_frontmatter_lacking_type_navigates goes RED when the
  tolerance is re-keyed on absence-of-frontmatter.
- test_missing_type_is_an_error goes RED when the index default leaks onto
  concept files. Its vehicle moved from index.md to a non-index file: it
  proves the concept-file rule, and an index.md vehicle now proves the
  opposite of what the test is named for. This also closes a real gap —
  nothing tested a non-index file WITH frontmatter but WITHOUT 'type'.

Goldens untouched (shared bundle has type: index; ingest golden index has no
frontmatter). Suite 627 -> 628 passed.
This commit is contained in:
Kjell Tore Guttormsen 2026-07-26 14:48:37 +02:00
commit f41264fbd3
2 changed files with 58 additions and 19 deletions

View file

@ -47,10 +47,11 @@ def _strip_matching_quotes(value: str) -> str:
return value
def parse_concept_file(path: Path) -> ConceptFile:
"""Parse frontmatter (leading ``---`` block, line-oriented ``key: value``) + body.
def _parse_frontmatter_and_body(path: Path) -> tuple[dict[str, str], str]:
"""Split a leading ``---`` block (line-oriented ``key: value``) from the body.
The single required field is ``type``; unknown fields are preserved as strings.
Unknown fields are preserved as strings. The ``type`` requirement is NOT applied
here it belongs to concept files, not to the index entry point.
"""
lines = path.read_text(encoding="utf-8").splitlines()
if not lines or lines[0].strip() != "---":
@ -64,30 +65,44 @@ def parse_concept_file(path: Path) -> ConceptFile:
key, sep, value = line.partition(":")
if sep:
frontmatter[key.strip()] = _strip_matching_quotes(value.strip())
return frontmatter, "\n".join(lines[body_start:]).strip()
def parse_concept_file(path: Path) -> ConceptFile:
"""Parse frontmatter (leading ``---`` block, line-oriented ``key: value``) + body.
The single required field is ``type``; unknown fields are preserved as strings.
"""
frontmatter, body = _parse_frontmatter_and_body(path)
if "type" not in frontmatter:
raise ValueError(f"{path.name}: frontmatter lacks the required field 'type'")
return ConceptFile(
path=path, frontmatter=frontmatter, body="\n".join(lines[body_start:]).strip()
)
return ConceptFile(path=path, frontmatter=frontmatter, body=body)
def _parse_index_entry(index_path: Path) -> ConceptFile:
"""Parse the bundle entry point, tolerating a frontmatter-less index (§3 Step 1).
"""Parse the bundle entry point, where ``type`` is not required (§3 Step 1).
method-spec §3 Step 1 renders the index as "the index body (the summary)" and
treats every OTHER file as a "non-index concept file" (`## {type}: {title}`
section) so the index is NOT a concept file, and it MAY omit frontmatter: a
generated index carrying only ``bundle_summary`` + cross-links (ingest spec §6,
frozen in the ingest golden) is valid. A frontmatter-ful index (the curated
convention, ``type: index``) still parses normally, its extra fields preserved.
When frontmatter is absent, the whole file is the body and ``type`` defaults to
``index`` so downstream ``.type`` reads never raise.
section) so the index is NOT a concept file, and the ``type`` requirement does
not reach it. It MAY omit frontmatter entirely (a generated index carrying only
``bundle_summary`` + cross-links, ingest spec §6, frozen in the ingest golden),
and it MAY carry frontmatter that says nothing about ``type`` (an OKF v0.2
generated index stamps ``okf_version`` there). In both cases ``type`` defaults to
``index`` so downstream ``.type`` reads never raise; other fields are preserved.
A curated index (``type: index``) is unaffected.
Keying this on the ABSENCE of a frontmatter block was the defect: a frontmatter-ful
index without ``type`` then raised out of ``parse_concept_file`` and killed the
whole navigation, not merely the index read.
"""
text = index_path.read_text(encoding="utf-8")
lines = text.splitlines()
if lines and lines[0].strip() == "---":
return parse_concept_file(index_path)
return ConceptFile(path=index_path, frontmatter={"type": _INDEX_TYPE}, body=text.strip())
if not lines or lines[0].strip() != "---":
return ConceptFile(path=index_path, frontmatter={"type": _INDEX_TYPE}, body=text.strip())
frontmatter, body = _parse_frontmatter_and_body(index_path)
frontmatter.setdefault("type", _INDEX_TYPE)
return ConceptFile(path=index_path, frontmatter=frontmatter, body=body)
def navigate_bundle(bundle_dir: Path) -> list[ConceptFile]:
@ -96,8 +111,8 @@ def navigate_bundle(bundle_dir: Path) -> list[ConceptFile]:
Targets containing a path separator are out-of-bundle and skipped; resolution is
boundary-checked against the bundle directory (fail-closed); broken links are
skipped, never raised. Repeated links are de-duplicated. The index entry point
may omit frontmatter (``_parse_index_entry``); non-index concept files still
require ``type``.
does not require ``type`` with or without a frontmatter block
(``_parse_index_entry``); non-index concept files still require it.
"""
index_path = bundle_dir / _INDEX_FILENAME
if not index_path.is_file():