Skip to content

[backend] CorpusBackend filesystem: DRY refactor of title-derivation logic across 4 sites #309

@dep0we

Description

@dep0we

Context

PR 1 of the CorpusBackend arc (#65) shipped FilesystemCorpusBackend in atomic_agents/corpus/filesystem.py. The logic that derives a page title from frontmatter (title: field) with a fallback to the first H1 heading in the body, and a further fallback to the page-name stem, appears at 4 separate call sites in that file. Any future change to the title-derivation rule must be applied in 4 places, creating drift risk.

Evidence

atomic_agents/corpus/filesystem.py -- title-derivation logic (frontmatter title: lookup, fallback to first # heading, fallback to page-name stem) appears in at least 4 methods (list_pages, read_page, read_version, and the version-restore path). Surfaced as a P3 polish finding during PR 1 review.

Proposed fix

Extract a _derive_title(name: str, frontmatter: dict, body: str) -> str private helper at module level (or as a static method on FilesystemCorpusBackend). Replace all 4 call sites with a call to the helper. No behavior change; the refactor is covered by the existing backend conformance tests.

Acceptance criteria

  • Title-derivation logic exists in exactly one place in filesystem.py.
  • All 4 prior call sites delegate to the extracted helper.
  • uv run pytest tests/test_corpus_filesystem_backend.py tests/test_corpus_protocol_conformance.py -q passes with zero regressions.

Source

PR 1 of #65 (PR #297), polish gap.

Metadata

Metadata

Assignees

No one assigned

    Labels

    backendProtocol-pattern backend abstractions (memory, logs, locks, etc.)polishOperational nice-to-haves

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions