F18.6 — Cache Markdown structure by text
| State | Closed |
| Parent | E18 |
| Iteration | Release 8 |
| Start Date | 2026-11-13 |
| Closed Date | 2026-11-13 |
| Predecessors | F18.4 |
| Source | Owner request, 2026-11-10 |
Stories: 1 Closed
| Story | State | Depends on |
|---|---|---|
| S18.6.1 — Share a bounded Markdown parse cache | Closed | — |
A caller that asks for headings, anchors, links and tables from the same page
currently pays for repeated Markdown parsing. Cache the parsed structure inside
MarkdownUtils, so applications need no cache wrappers of their own.
Design
The public API and its values are unchanged: headings, links and tables
return fresh lists and anchors a fresh set, so one caller's mutation never
changes another's result. One private functools.lru_cache(maxsize=2048), keyed
by the complete input text, holds a frozen result extracted from one parse; the
cache is process-local, bounded by entries rather than bytes, and concurrent
misses may compute the same entry more than once. The rn-forge-commons text
guide (docs/guides/text.md, Markdown) describes the reuse.
S18.6.1 — Share a bounded Markdown parse cache
State: Closed
Outcome: shipped as a private cache in rn_forge.commons.text.markdown,
with cache and mutation-isolation tests and an [Unreleased] performance
changelog entry.
Acceptance:
- A cold-cache test wraps the parser's
parsemethod and callsheadings,anchors,title,links,tablesandstrip_fenced_codeon one document, then repeats them in a different order. There is exactly one parser call for that text in this sequential test. Each helper can populate a cold cache correctly, independent of which helper is called first. - Mutating a returned headings list, links list, tables list or anchors set leaves all later results unchanged. The returned mutable containers are distinct across calls, including for empty input.
- A different string produces a cache miss and the changed result. A distinct string object with equal content reuses the same entry. After 2049 distinct texts, the cache has at most 2048 entries and querying an evicted entry parses it again. Cache-specific tests clean up even when an assertion fails.
- Existing Markdown tests pass unchanged. Add a mixed document covering setext and repeated headings, inline markup and code, inline/reference/image links, percent-encoded targets, GFM tables and fenced code. All six helpers return the same expected values on cold and warm calls. Preserve CRLF and the absence of a final newline when removing fenced code.
task test,task typecheckandtask docs:buildpass; the existing import contracts still pass throughtask lint. Performance acceptance is the parser call count, not a machine-dependent elapsed-time threshold.
Considered and rejected
- A separate cache on each helper. It still parses one document separately for headings, links and tables.
- Caching public lists and sets. One caller's mutation changes another caller's result.
- Caching the mutable token stream. A compact immutable extracted result keeps parser internals private and makes result isolation explicit.
- An unbounded cache or one keyed only by a file path. The former retains every document in a long-lived process; the latter can return stale content.
Adoption by consumers and their dependency upgrades are separate work and do not gate this feature.