Skip to content

Commit 28145f0

Browse files
cdeustclaude
andauthored
refactor(wiki): extract cohesive collaborators from wiki_pages.py (#111)
Move Function / Split Module (Fowler) — wiki_pages.py (460 lines) split along its three cohesive concerns into new core modules, with wiki_pages.py becoming the composed public-API entry point (all prior exports preserved, same names/signatures — this is the module's public contract per issue #106's coordination requirement with in-flight PR #109). - wiki_frontmatter.py (164 lines) — PageDocument, parse_page, render_page, frontmatter parsing/rendering internals. - wiki_page_builders.py (230 lines) — build_adr/spec/file_doc/note/lesson/ convention/reference, ADR_STATUSES, maturity_label, sources/related section helpers. - wiki_index.py (79 lines) — build_index (INDEX.md generation). - wiki_pages.py (54 lines) — re-exports the full prior public API. Before: 460 lines, 1 file. After: 527 lines across 4 files, none exceeding 230 lines (§4.1/§4.3). Tests: 466 passed / 1 pre-existing failure (missing psycopg in this env, unrelated to wiki_pages) before and after — 0 regressions, 0 tests modified. ruff format --check + ruff check: pass on all 4 files. Co-authored-by: Claude <[email protected]>
1 parent 3eb43f2 commit 28145f0

4 files changed

Lines changed: 519 additions & 452 deletions

File tree

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
"""Wiki page frontmatter parser + PageDocument model — pure, deterministic.
2+
3+
Parses YAML-style frontmatter (``---``…``---``) into a plain dict so
4+
handlers can round-trip metadata without depending on a YAML library, and
5+
renders a ``PageDocument`` back to markdown text.
6+
"""
7+
8+
from __future__ import annotations
9+
10+
from dataclasses import dataclass, field
11+
from datetime import datetime, timezone
12+
13+
14+
@dataclass(frozen=True)
15+
class PageDocument:
16+
"""Parsed representation of a wiki page."""
17+
18+
frontmatter: dict[str, object] = field(default_factory=dict)
19+
body: str = ""
20+
21+
22+
def _now_iso() -> str:
23+
return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
24+
25+
26+
def _format_frontmatter(fm: dict[str, object]) -> str:
27+
"""Emit a minimal YAML-ish frontmatter block. Sorted keys, scalars only.
28+
29+
Lists are rendered inline (``[a, b, c]``). Nested dicts are not
30+
supported — keep metadata flat.
31+
"""
32+
if not fm:
33+
return ""
34+
lines = ["---"]
35+
for key in sorted(fm):
36+
value = fm[key]
37+
if isinstance(value, list):
38+
rendered = "[" + ", ".join(str(v) for v in value) + "]"
39+
elif value is None:
40+
rendered = ""
41+
else:
42+
rendered = str(value)
43+
lines.append(f"{key}: {rendered}")
44+
lines.append("---")
45+
lines.append("")
46+
return "\n".join(lines)
47+
48+
49+
def _strip_inline_list(value: str) -> list[str]:
50+
inner = value.strip()
51+
if inner.startswith("[") and inner.endswith("]"):
52+
inner = inner[1:-1]
53+
return [item.strip() for item in inner.split(",") if item.strip()]
54+
55+
56+
def _clean_scalar_value(key: str, raw_stripped: str) -> str:
57+
"""Normalize a non-list frontmatter scalar value.
58+
59+
precondition: ``raw_stripped`` is the whitespace-trimmed text found
60+
after the FIRST ``:`` on a frontmatter line (i.e. ``line.partition(":")``
61+
already removed exactly one ``<key>:`` label); ``raw_stripped`` is
62+
non-empty and is not an inline ``[...]`` list (both handled by the
63+
caller before this is reached).
64+
postcondition: returns ``raw_stripped`` with (a) a duplicated leading
65+
``"<key>: "`` label removed, at most once, matched case-insensitively
66+
against ``key`` — this repairs content where the author's own
67+
frontmatter emission echoed the key a second time inside its value
68+
(observed on disk: ``title: title: "Public API surface: ..."``,
69+
written verbatim by an LLM-authored page routed through
70+
``write_governed_page``, which persists caller-supplied markdown
71+
without re-deriving frontmatter); (b) one matching pair of surrounding
72+
quote characters (``"`` or ``'``) removed, mirroring the quote-stripping
73+
the block-list branch (``items.append(...strip("\"'"))``, above) and
74+
``_strip_inline_list`` already perform for list values — the scalar
75+
branch previously had no equivalent, so a value legitimately quoted
76+
per YAML convention because it contains a colon (e.g.
77+
``title: "Public API surface: automatised-pipeline"``) kept its
78+
literal quote characters. A value that merely starts with the key
79+
name as a normal word (e.g. ``title: titleist golf clubs``) is
80+
unaffected — the duplicate-label check requires the exact
81+
``"<key>:"`` token, not just a shared prefix.
82+
"""
83+
value = raw_stripped
84+
dup_prefix = f"{key}:"
85+
if value.lower().startswith(dup_prefix.lower()):
86+
value = value[len(dup_prefix) :].strip()
87+
if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
88+
value = value[1:-1]
89+
return value
90+
91+
92+
def parse_page(text: str) -> PageDocument:
93+
"""Parse a page's frontmatter + body. Tolerant of missing frontmatter.
94+
95+
Handles two YAML list forms:
96+
97+
* Inline: ``tags: [a, b, c]``
98+
* Block: ``tags:\\n - a\\n - b``
99+
100+
Block-style is required for ``curation_gaps`` and other multi-value
101+
metadata the file-doc skeletons emit.
102+
"""
103+
if not text.startswith("---\n") and not text.startswith("---\r\n"):
104+
return PageDocument(body=text)
105+
lines = text.splitlines()
106+
if not lines or lines[0].strip() != "---":
107+
return PageDocument(body=text)
108+
fm: dict[str, object] = {}
109+
body_start = len(lines)
110+
idx = 1
111+
while idx < len(lines):
112+
if lines[idx].strip() == "---":
113+
body_start = idx + 1
114+
break
115+
line = lines[idx]
116+
if ":" not in line:
117+
idx += 1
118+
continue
119+
# Block-list detection: a key with no value followed by indented
120+
# `` - item`` lines collects into a list.
121+
key_part, _, raw = line.partition(":")
122+
key = key_part.strip()
123+
raw_stripped = raw.strip()
124+
if raw_stripped == "":
125+
# Possibly a block list. Peek ahead.
126+
items: list[str] = []
127+
j = idx + 1
128+
while j < len(lines):
129+
peek = lines[j]
130+
if peek.strip() == "---":
131+
break
132+
stripped = peek.lstrip()
133+
if peek.startswith((" ", "\t")) and stripped.startswith("- "):
134+
items.append(stripped[2:].strip().strip("\"'"))
135+
j += 1
136+
continue
137+
break
138+
if items:
139+
fm[key] = items
140+
idx = j
141+
continue
142+
# Empty value, no list — keep as empty string.
143+
fm[key] = ""
144+
idx += 1
145+
continue
146+
if raw_stripped.startswith("[") and raw_stripped.endswith("]"):
147+
fm[key] = _strip_inline_list(raw_stripped)
148+
else:
149+
fm[key] = _clean_scalar_value(key, raw_stripped)
150+
idx += 1
151+
body_lines = lines[body_start:]
152+
while body_lines and body_lines[0] == "":
153+
body_lines.pop(0)
154+
return PageDocument(frontmatter=fm, body="\n".join(body_lines))
155+
156+
157+
def render_page(doc: PageDocument) -> str:
158+
"""Render a PageDocument back to markdown text."""
159+
header = _format_frontmatter(doc.frontmatter)
160+
if header and doc.body:
161+
return header + doc.body + ("" if doc.body.endswith("\n") else "\n")
162+
if header:
163+
return header
164+
return doc.body + ("" if doc.body.endswith("\n") else "\n") if doc.body else ""

‎mcp_server/core/wiki_index.py‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
"""Wiki INDEX.md builder — pure, deterministic.
2+
3+
Groups wiki pages by domain then kind into a structured markdown index.
4+
"""
5+
6+
from __future__ import annotations
7+
8+
9+
def build_index(page_paths: list[str]) -> str:
10+
"""Build a structured INDEX.md grouped by domain then kind.
11+
12+
Each path is relative to the wiki root. Supports both flat
13+
(``notes/foo.md``) and domain-scoped (``notes/cortex/foo.md``) paths.
14+
Pure function — no I/O.
15+
"""
16+
from mcp_server.core.wiki_layout import PAGE_KINDS
17+
18+
# Parse paths into (kind, domain, filename, full_path)
19+
entries: list[tuple[str, str, str, str]] = []
20+
for p in page_paths:
21+
parts = p.split("/")
22+
if len(parts) >= 2 and parts[0] in PAGE_KINDS:
23+
kind = parts[0]
24+
if len(parts) >= 3:
25+
domain = parts[1]
26+
filename = parts[-1].removesuffix(".md")
27+
else:
28+
domain = "_general"
29+
filename = parts[-1].removesuffix(".md")
30+
entries.append((kind, domain, filename, p))
31+
32+
total = len(entries)
33+
domains = sorted({e[1] for e in entries})
34+
domain_count = len([d for d in domains if d != "_general"])
35+
36+
# Group by domain → kind → pages
37+
tree: dict[str, dict[str, list[tuple[str, str]]]] = {}
38+
for kind, domain, filename, path in entries:
39+
tree.setdefault(domain, {}).setdefault(kind, []).append((filename, path))
40+
41+
_KIND_LABELS = {
42+
"adr": "Architecture Decisions",
43+
"specs": "Specifications",
44+
"guides": "Guides & How-To",
45+
"reference": "Reference",
46+
"conventions": "Conventions",
47+
"lessons": "Lessons Learned",
48+
"notes": "Notes",
49+
"journal": "Journal",
50+
"files": "File Documentation",
51+
}
52+
53+
lines = [
54+
"# Cortex Knowledge Base",
55+
"",
56+
f"**{total} pages** across {domain_count} domains",
57+
"",
58+
]
59+
60+
# Render each domain
61+
for domain in sorted(tree.keys(), key=lambda d: "zzz" if d == "_general" else d):
62+
kinds = tree[domain]
63+
page_count = sum(len(pages) for pages in kinds.values())
64+
label = "Global" if domain == "_general" else domain.replace("-", " ").title()
65+
lines.append(f"## {label} ({page_count} pages)")
66+
lines.append("")
67+
68+
for kind in PAGE_KINDS:
69+
pages = kinds.get(kind, [])
70+
if not pages:
71+
continue
72+
kind_label = _KIND_LABELS.get(kind, kind.title())
73+
lines.append(f"### {kind_label}")
74+
lines.append("")
75+
for filename, path in sorted(pages):
76+
lines.append(f"- [{filename}]({path})")
77+
lines.append("")
78+
79+
return "\n".join(lines)

0 commit comments

Comments
 (0)