Skip to content

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 parse method and calls headings, anchors, title, links, tables and strip_fenced_code on 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 typecheck and task docs:build pass; the existing import contracts still pass through task 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.