mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:07:29 +08:00
## Description `_merge_into_file` (`headroom/learn/writer.py`) located the managed block with `block_pattern` (first occurrence of the start marker to the nearest end marker) whenever `_MARKER_START in existing`. Two consequences, both reported in #4339: 1. Hand-written prose that quotes the start-marker string became the start of the match, so `--apply` replaced everything from that mention through the real block's end marker, deleting the hand-written text in between. 2. A file holding the start marker but no end marker matched nothing: `sub()` returned the file unchanged and every recommendation of the run was silently dropped while the CLI still printed `[WROTE]`. The block is now identified by the shape `_build_section` writes: a line that is **exactly** the start marker through the next line that is **exactly** the end marker. A marker quoted inside prose (sharing its line with other text, or indented) or inside a fenced code block (a Markdown example) is not a boundary, and a start marker with no end marker before the next start marker is skipped. One helper, `_find_managed_block()`, is used by every reader and writer of the block in this module, so the block that is parsed is the block that is replaced. The first commit (2c6853ea) used "the last start marker that has an end marker after it"; review showed that only moved the problem to prose after the block, and left `_parse_prior_recommendations` reading a different span. The second commit (eba6458b) replaces it with the line-based rule above, and the third (40880d1e, after review) skips marker lines inside fenced code blocks. Closes #4339 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/learn/writer.py`: new `_find_managed_block(text) -> (start, end) | None` (linear scan of lines; whole-line markers only; marker lines inside ``` / ~~~ fences ignored, CommonMark-style open/close rules; first complete block). `extract_marker_block`, `_parse_prior_recommendations`, `_merge_into_file`, `_strip_marker_block` and the two legacy-migration presence checks in `_migrate_legacy_block` use it. With no block (including a dangling start marker), `_merge_into_file` appends a fresh section as for a file with no markers. `_MARKER_PATTERN` and the `block_pattern` import are removed from this module; `managed_block.block_pattern` and `sanitize_block_text` are unchanged. - `tests/test_learn/test_writer.py` (`TestClaudeCodeWriter`), four tests: - `test_merge_keeps_prose_that_quotes_the_start_marker_above_the_block` and `test_merge_appends_a_block_when_the_end_marker_is_missing` (the two cases in #4339; both fail on `main`); - `test_merge_keeps_prose_quoting_both_markers_after_the_block` and `test_prior_sections_come_from_the_block_not_from_quoting_prose` (the two layouts from the first review; both fail on the first commit); - `test_merge_leaves_a_fenced_example_of_the_block_untouched` (the fenced-example layout from the second review; fails on eba6458b/35cf4a98) and `test_fenced_code_inside_the_block_does_not_hide_its_end_marker` (a closed code fence in a recommendation body). Behaviour notes: a file holding two complete blocks used to have both replaced by `sub()`; the merge now rewrites the first one and leaves the second as text, and `_strip_marker_block` (legacy migration) still removes every complete block. An unclosed code fence inside the managed block would hide its end marker (the merge then appends a fresh block); recommendation bodies with balanced fences are covered by a test. ## Testing - [x] Unit tests pass (`pytest`) — `tests/test_learn/`, `tests/test_managed_block_injection.py`, `tests/test_memory/test_traffic_learner.py`: 617 passed, 10 skipped (on40880d1e) - [x] Linting passes (`ruff check .`) — on the two changed files, plus `ruff format --check` - [x] Type checking passes (`mypy headroom`) — run on `headroom/learn/writer.py`; the single reported error is in `headroom/providers/model_metadata.py:79` and is identical on `main` - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # the four tests against the FIRST commit2c6853ea(fail-before for the two review layouts) $ pytest tests/test_learn/test_writer.py -q -k "quotes_the_start_marker or end_marker_is_missing or both_markers_after or quoting_prose" --tb=line tests/test_learn/test_writer.py:379: AssertionError: assert 2 == 1 # "### Manual policy" copied into the block FAILED tests/test_learn/test_writer.py::TestClaudeCodeWriter::test_merge_keeps_prose_quoting_both_markers_after_the_block FAILED tests/test_learn/test_writer.py::TestClaudeCodeWriter::test_prior_sections_come_from_the_block_not_from_quoting_prose 2 failed, 2 passed, 44 deselected in 1.82s # witheba6458b(pass-after) 4 passed, 44 deselected in 0.99s # fenced-example case (second review) on35cf4a98, then on40880d1eFAILED tests/test_learn/test_writer.py::TestClaudeCodeWriter::test_merge_leaves_a_fenced_example_of_the_block_untouched 1 failed, 1 passed, 48 deselected 2 passed, 48 deselected in 1.14s # the #4339 cases against main4c7acba5(from the first round) 2 failed (hand-written rule line deleted; file returned unchanged) $ pytest tests/test_learn tests/test_managed_block_injection.py tests/test_memory/test_traffic_learner.py -q 617 passed, 10 skipped, 1 warning in 10.90s $ ruff check headroom/learn/writer.py tests/test_learn/test_writer.py && ruff format --check headroom/learn/writer.py tests/test_learn/test_writer.py All checks passed! 2 files already formatted ``` ## Real Behavior Proof - Environment: WSL2 Ubuntu, Python 3.12.15, pytest 9.1.1, ruff 0.17.1, mypy 2.4.0; a clone of this fork with the core runtime dependencies only - Exact command / steps: on the PR branch at the first commit, apply only the two new tests and run the four `-k` tests above (the two review layouts fail, the two #4339 cases pass); apply the source change and run them again (all pass); then the learn, managed-block and traffic-learner suites, ruff and mypy as pasted - Observed result: prose that quotes the start marker above the block, prose that quotes both markers below it, and headings inside such prose all stay hand-written text: the managed block is the one rebuilt, its prior sections are read from that same block, and a dangling start marker gets a fresh section appended instead of losing the run's recommendations - Not tested: `headroom learn --apply` end to end through the CLI (only `_merge_into_file`, the parser and the writer tests); the memory writers, which share `block_pattern` but are not changed here ## Runtime Rollout Safety - Rollout-managed feature(s): none (`headroom learn` is not behind a rollout flag) - Minimum rollout channel: n/a (not rollout-managed) - Stable/default behavior changed: only for files with marker strings quoted in prose, a dangling start marker, or two complete blocks (see Behaviour notes); a file the writer produced merges exactly as before - Kill switch / disable path: none added; `headroom learn` without `--apply` never writes - Unsafe override required: no - Qualification impact: none known; no `CHANGELOG.md` edit (release-please) - Rollback path: revert the two commits ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation (none needed) - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes Produced with AI assistance (Claude Code) operated by me (HetCreep); the test runs above were executed on my machine on a clone of this fork. Related: #3850 (introduced `managed_block.py` and the nearest-end-marker rule). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
990 lines
41 KiB
Python
990 lines
41 KiB
Python
"""Tests for recommendation writer — marker-based file updates."""
|
|
|
|
import subprocess
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
from headroom.learn.models import ProjectInfo, Recommendation, RecommendationTarget
|
|
from headroom.learn.writer import (
|
|
_MARKER_END,
|
|
_MARKER_START,
|
|
ClaudeCodeWriter,
|
|
CodexWriter,
|
|
GeminiWriter,
|
|
GrokWriter,
|
|
_merge_into_file,
|
|
_parse_prior_recommendations,
|
|
_read_text_tolerant,
|
|
extract_marker_block,
|
|
)
|
|
|
|
|
|
def _project(tmp_path: Path) -> ProjectInfo:
|
|
proj_dir = tmp_path / "myproject"
|
|
proj_dir.mkdir()
|
|
data_dir = tmp_path / "data"
|
|
data_dir.mkdir()
|
|
memory_dir = data_dir / "memory"
|
|
memory_dir.mkdir()
|
|
return ProjectInfo(
|
|
name="myproject",
|
|
project_path=proj_dir,
|
|
data_path=data_dir,
|
|
)
|
|
|
|
|
|
def _rec(target: RecommendationTarget, section: str, content: str) -> Recommendation:
|
|
return Recommendation(
|
|
target=target, section=section, content=content, confidence=0.8, evidence_count=5
|
|
)
|
|
|
|
|
|
class TestClaudeCodeWriter:
|
|
def test_dry_run_does_not_write(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
result = writer.write(recs, proj, dry_run=True)
|
|
|
|
assert result.dry_run is True
|
|
assert len(result.files_written) == 1
|
|
# File should NOT exist (dry run)
|
|
claude_local = proj.project_path / "CLAUDE.local.md"
|
|
assert not claude_local.exists()
|
|
# Default target is the personal CLAUDE.local.md, never the shared CLAUDE.md
|
|
assert result.files_written[0].name == "CLAUDE.local.md"
|
|
|
|
def test_apply_writes_claude_local_md(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use `uv run python`")]
|
|
|
|
result = writer.write(recs, proj, dry_run=False)
|
|
|
|
assert result.dry_run is False
|
|
# Learnings go to the personal, gitignored CLAUDE.local.md by default...
|
|
claude_local = proj.project_path / "CLAUDE.local.md"
|
|
assert claude_local.exists()
|
|
content = claude_local.read_text()
|
|
assert "uv run python" in content
|
|
assert _MARKER_START in content
|
|
assert _MARKER_END in content
|
|
# ...and never touch the team-shared CLAUDE.md.
|
|
assert not (proj.project_path / "CLAUDE.md").exists()
|
|
|
|
def test_apply_writes_memory_md(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.MEMORY_FILE, "Retry Prevention", "- Don't retry globs")]
|
|
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
memory_md = proj.data_path / "memory" / "MEMORY.md"
|
|
assert memory_md.exists()
|
|
assert "Don't retry globs" in memory_md.read_text()
|
|
|
|
def test_hand_written_claude_md_left_untouched(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
original = "# My Project\n\nExisting instructions here.\n"
|
|
claude_md.write_text(original)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
# A hand-written CLAUDE.md with no headroom block is left exactly as-is.
|
|
assert claude_md.read_text() == original
|
|
# Learnings land in the personal CLAUDE.local.md instead.
|
|
local_content = (proj.project_path / "CLAUDE.local.md").read_text()
|
|
assert "Use uv" in local_content
|
|
|
|
def test_carries_forward_prior_sections_not_resurfaced(self, tmp_path):
|
|
"""Re-running learn must not drop prior sections that the new run didn't re-surface."""
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.local.md"
|
|
prior_block = (
|
|
f"# My Project\n\n{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
|
|
"### Large Files\n"
|
|
"*~15,000 tokens/session saved*\n"
|
|
"- src/App.tsx is huge\n\n"
|
|
"### Build Commands\n"
|
|
"- cargo check from src-tauri/\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
claude_md.write_text(prior_block)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
content = claude_md.read_text()
|
|
assert "My Project" in content
|
|
# New section present
|
|
assert "Use uv" in content
|
|
# Prior sections preserved (neither heading re-surfaced by the new run)
|
|
assert "### Large Files" in content
|
|
assert "src/App.tsx is huge" in content
|
|
assert "### Build Commands" in content
|
|
assert "cargo check from src-tauri/" in content
|
|
# Tokens annotation round-tripped
|
|
assert "*~15,000 tokens/session saved*" in content
|
|
# Still exactly one marker pair
|
|
assert content.count(_MARKER_START) == 1
|
|
assert content.count(_MARKER_END) == 1
|
|
|
|
def test_new_run_overrides_same_named_prior_section(self, tmp_path):
|
|
"""When a section appears in both prior and new, the new run wins."""
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.local.md"
|
|
prior_block = (
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
|
|
"### Environment\n"
|
|
"- old stale environment note\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
claude_md.write_text(prior_block)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- fresh environment note")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
content = claude_md.read_text()
|
|
assert "fresh environment note" in content
|
|
assert "old stale environment note" not in content
|
|
# Only one Environment section in the final block
|
|
assert content.count("### Environment") == 1
|
|
|
|
def test_opt_in_same_section_merge_preserves_prior_pattern_items(self, tmp_path):
|
|
context_file = tmp_path / "AGENTS.md"
|
|
context_file.write_text(
|
|
"<!-- headroom:learn:start -->\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Learned: preference\n"
|
|
"- Keep the established queue <!-- headroom:pattern-id:queue -->\n"
|
|
"- Keep local reviews\n\n"
|
|
"<!-- headroom:learn:end -->\n"
|
|
)
|
|
recommendation = _rec(
|
|
RecommendationTarget.CONTEXT_FILE,
|
|
"Learned: preference",
|
|
"- Use the updated queue <!-- headroom:pattern-id:queue -->\n"
|
|
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
|
|
)
|
|
recommendation.preserve_prior_items = True
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert "Use the updated queue" in final
|
|
assert "Keep the established queue" not in final
|
|
assert final.count("Keep local reviews") == 1
|
|
|
|
def test_active_ids_keep_unbatched_items_and_drop_expired_ones(self, tmp_path):
|
|
"""The removal invariant: preservation is bounded by the active id set.
|
|
|
|
``ripgrep`` is active but was left out of this batch (ranking/top-N),
|
|
so it must survive. ``vendored`` is no longer active, so it must be
|
|
deleted rather than pinned into the file forever.
|
|
"""
|
|
context_file = tmp_path / "AGENTS.md"
|
|
context_file.write_text(
|
|
"<!-- headroom:learn:start -->\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Learned: preference\n"
|
|
"- Keep local reviews <!-- headroom:pattern-id:reviews -->\n"
|
|
"- Prefer ripgrep over grep <!-- headroom:pattern-id:ripgrep -->\n"
|
|
"- Build against the vendored SDK <!-- headroom:pattern-id:vendored -->\n\n"
|
|
"<!-- headroom:learn:end -->\n"
|
|
)
|
|
recommendation = _rec(
|
|
RecommendationTarget.CONTEXT_FILE,
|
|
"Learned: preference",
|
|
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
|
|
)
|
|
recommendation.preserve_prior_items = True
|
|
recommendation.active_item_ids = frozenset({"reviews", "ripgrep"})
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert final.count("Keep local reviews") == 1
|
|
assert "Prefer ripgrep over grep" in final
|
|
assert "Build against the vendored SDK" not in final
|
|
assert "headroom:pattern-id:vendored" not in final
|
|
|
|
def test_active_ids_drop_untagged_legacy_items(self, tmp_path):
|
|
"""Untagged prior items pre-date id tagging and are not a lifecycle signal.
|
|
|
|
The still-active one comes back with an id from the current run and
|
|
collapses into a single bullet; the one the learner dropped goes away.
|
|
"""
|
|
context_file = tmp_path / "AGENTS.md"
|
|
context_file.write_text(
|
|
"<!-- headroom:learn:start -->\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Learned: preference\n"
|
|
"- Keep local reviews\n"
|
|
"- Build against the vendored SDK\n\n"
|
|
"<!-- headroom:learn:end -->\n"
|
|
)
|
|
recommendation = _rec(
|
|
RecommendationTarget.CONTEXT_FILE,
|
|
"Learned: preference",
|
|
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
|
|
)
|
|
recommendation.preserve_prior_items = True
|
|
recommendation.active_item_ids = frozenset({"reviews"})
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert final.count("Keep local reviews") == 1
|
|
assert "headroom:pattern-id:reviews" in final
|
|
assert "Build against the vendored SDK" not in final
|
|
|
|
def test_without_active_ids_prior_items_are_unioned(self, tmp_path):
|
|
"""No lifecycle signal — every producer that predates it keeps the union."""
|
|
context_file = tmp_path / "AGENTS.md"
|
|
context_file.write_text(
|
|
"<!-- headroom:learn:start -->\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Learned: preference\n"
|
|
"- Keep local reviews <!-- headroom:pattern-id:reviews -->\n"
|
|
"- Build against the vendored SDK <!-- headroom:pattern-id:vendored -->\n"
|
|
"- Untagged leftover\n\n"
|
|
"<!-- headroom:learn:end -->\n"
|
|
)
|
|
recommendation = _rec(
|
|
RecommendationTarget.CONTEXT_FILE,
|
|
"Learned: preference",
|
|
"- Keep local reviews <!-- headroom:pattern-id:reviews -->",
|
|
)
|
|
recommendation.preserve_prior_items = True
|
|
assert recommendation.active_item_ids is None
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert final.count("Keep local reviews") == 1
|
|
assert "Build against the vendored SDK" in final
|
|
assert "Untagged leftover" in final
|
|
|
|
def test_replacing_existing_block_handles_literal_backslash_escapes(self, tmp_path):
|
|
"""LLM text with backslash escapes must not be interpreted as a regex replacement."""
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
claude_md.write_text(
|
|
f"# Existing\n\n{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Windows Paths\n"
|
|
"- stale\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
|
|
full_content = _merge_into_file(
|
|
claude_md,
|
|
[
|
|
_rec(
|
|
RecommendationTarget.CONTEXT_FILE,
|
|
"Windows Paths",
|
|
r"- Keep the literal \u sequence and C:\Users\john.doe\repo path",
|
|
)
|
|
],
|
|
)
|
|
|
|
assert r"\u sequence" in full_content
|
|
assert r"C:\Users\john.doe\repo" in full_content
|
|
assert "stale" not in full_content
|
|
|
|
def test_merge_keeps_prose_that_quotes_the_start_marker_above_the_block(self, tmp_path):
|
|
"""Prose quoting the start marker above the block must survive the rewrite."""
|
|
context_file = tmp_path / "CLAUDE.local.md"
|
|
prose = f"The block below starts with {_MARKER_START} and is managed."
|
|
context_file.write_text(
|
|
f"{prose}\n"
|
|
"- Hand-written rule: never force-push\n\n"
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Environment\n"
|
|
"- old bullet\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert "- Hand-written rule: never force-push" in final
|
|
assert prose in final
|
|
assert "- Use uv" in final
|
|
assert final.count(_MARKER_START) == 2
|
|
assert final.count(_MARKER_END) == 1
|
|
|
|
def test_merge_appends_a_block_when_the_end_marker_is_missing(self, tmp_path):
|
|
"""A start marker with no end marker is not a block: the recommendations must land."""
|
|
context_file = tmp_path / "CLAUDE.local.md"
|
|
original = f"{_MARKER_START}\n- Hand-written rule: never force-push\n"
|
|
context_file.write_text(original)
|
|
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert final != original
|
|
assert "- Use uv" in final
|
|
assert "- Hand-written rule: never force-push" in final
|
|
|
|
def test_merge_keeps_prose_quoting_both_markers_after_the_block(self, tmp_path):
|
|
"""Marker quotes in prose below the block are hand-written text, not a second block."""
|
|
context_file = tmp_path / "CLAUDE.local.md"
|
|
context_file.write_text(
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Environment\n"
|
|
"- old bullet\n\n"
|
|
f"{_MARKER_END}\n\n"
|
|
f"Example: {_MARKER_START}\n"
|
|
"- Hand-written rule: never force-push\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert "- Hand-written rule: never force-push" in final
|
|
assert final.startswith(f"{_MARKER_START}\n## Headroom Learned Patterns")
|
|
block = final[: final.index(_MARKER_END)]
|
|
assert "- Use uv" in block
|
|
assert "- old bullet" in block
|
|
assert final.count(f"Example: {_MARKER_START}") == 1
|
|
|
|
def test_prior_sections_come_from_the_block_not_from_quoting_prose(self, tmp_path):
|
|
"""Headings in prose that quotes the start marker must not become generated sections."""
|
|
context_file = tmp_path / "CLAUDE.local.md"
|
|
context_file.write_text(
|
|
f"Example: {_MARKER_START}\n"
|
|
"### Manual policy\n"
|
|
"- Hand-written rule: never force-push\n\n"
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Environment\n"
|
|
"- old bullet\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert final.count("### Manual policy") == 1
|
|
block = final[final.index(f"\n{_MARKER_START}\n") :]
|
|
assert "### Manual policy" not in block
|
|
assert "### Environment" in block
|
|
assert "- Use uv" in block
|
|
|
|
def test_merge_leaves_a_fenced_example_of_the_block_untouched(self, tmp_path):
|
|
"""Markers inside a fenced Markdown example are not the managed block."""
|
|
context_file = tmp_path / "CLAUDE.local.md"
|
|
example = f"```markdown\n{_MARKER_START}\nEXAMPLE_SENTINEL\n{_MARKER_END}\n```\n"
|
|
context_file.write_text(
|
|
"How the managed block looks:\n\n" + example + "\n"
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Environment\n"
|
|
"- old bullet\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert example in final
|
|
real_block = final[final.index(example) + len(example) :]
|
|
assert "- Use uv" in real_block
|
|
assert "- old bullet" in real_block
|
|
assert "- Use uv" not in final[: final.index(example) + len(example)]
|
|
|
|
def test_fenced_code_inside_the_block_does_not_hide_its_end_marker(self, tmp_path):
|
|
"""A closed code fence in a recommendation body keeps the block recognisable."""
|
|
context_file = tmp_path / "CLAUDE.local.md"
|
|
context_file.write_text(
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n\n"
|
|
"### Build\n"
|
|
"```bash\nmake test\n```\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
recommendation = _rec(RecommendationTarget.CONTEXT_FILE, "Tooling", "- Use uv")
|
|
|
|
final = _merge_into_file(context_file, [recommendation])
|
|
|
|
assert final.count(_MARKER_START) == 1
|
|
assert final.count(_MARKER_END) == 1
|
|
assert "- Use uv" in final
|
|
|
|
def test_memory_md_carry_forward(self, tmp_path):
|
|
"""Carry-forward also works for MEMORY.md."""
|
|
proj = _project(tmp_path)
|
|
memory_md = proj.data_path / "memory" / "MEMORY.md"
|
|
memory_md.write_text(
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
|
|
"### User Workflow Preferences\n"
|
|
"- User rejects sleep-based polling\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [
|
|
_rec(RecommendationTarget.MEMORY_FILE, "Related Codebases", "- web app at ~/Code/web")
|
|
]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
content = memory_md.read_text()
|
|
assert "User rejects sleep-based polling" in content
|
|
assert "web app at ~/Code/web" in content
|
|
|
|
def test_section_without_tokens_annotation_round_trips(self, tmp_path):
|
|
"""Prior sections emitted without a tokens annotation must still carry forward cleanly."""
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.local.md"
|
|
claude_md.write_text(
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
|
|
"### Misc\n"
|
|
"- one-liner pattern\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Other", "- new one")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
content = claude_md.read_text()
|
|
assert "### Misc" in content
|
|
assert "one-liner pattern" in content
|
|
# No spurious tokens annotation injected for a prior that didn't have one
|
|
misc_idx = content.index("### Misc")
|
|
after_misc = content[misc_idx : misc_idx + 200]
|
|
assert "tokens/session saved" not in after_misc
|
|
|
|
def test_appends_to_existing_memory_md(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
memory_md = proj.data_path / "memory" / "MEMORY.md"
|
|
memory_md.write_text("# Existing Memory\n\nSome facts.\n")
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.MEMORY_FILE, "Retry Prevention", "- New pattern")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
content = memory_md.read_text()
|
|
assert "Existing Memory" in content
|
|
assert "Some facts" in content
|
|
assert "New pattern" in content
|
|
|
|
|
|
def _legacy_block(section: str, body: str) -> str:
|
|
return (
|
|
f"# My Project\n\nExisting instructions.\n\n{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"*Auto-generated by `headroom learn` on 2026-01-01 — do not edit manually*\n\n"
|
|
f"### {section}\n{body}\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
|
|
|
|
class TestContextTargetOverride:
|
|
"""--target / set_context_target controls where CONTEXT_FILE recs are written."""
|
|
|
|
def test_target_override_relative_path(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
writer = ClaudeCodeWriter()
|
|
writer.set_context_target("CLAUDE.md")
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
# Explicit target opts back into the team-shared CLAUDE.md.
|
|
assert (proj.project_path / "CLAUDE.md").exists()
|
|
assert "Use uv" in (proj.project_path / "CLAUDE.md").read_text()
|
|
assert not (proj.project_path / "CLAUDE.local.md").exists()
|
|
|
|
def test_target_override_via_constructor(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
writer = ClaudeCodeWriter(context_target="docs/LEARNINGS.md")
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
target = proj.project_path / "docs" / "LEARNINGS.md"
|
|
assert target.exists()
|
|
assert "Use uv" in target.read_text()
|
|
|
|
def test_target_absolute_path(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
abs_target = tmp_path / "elsewhere" / "NOTES.md"
|
|
writer = ClaudeCodeWriter(context_target=str(abs_target))
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
assert abs_target.exists()
|
|
assert "Use uv" in abs_target.read_text()
|
|
|
|
|
|
class TestLegacyClaudeMdMigration:
|
|
"""A stale headroom block in the shared CLAUDE.md migrates to CLAUDE.local.md."""
|
|
|
|
def test_migrates_block_and_strips_legacy(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
claude_md.write_text(_legacy_block("Build Commands", "- cargo check from src-tauri/"))
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
result = writer.write(recs, proj, dry_run=False)
|
|
|
|
# Hand-written content stays in CLAUDE.md; the headroom block is gone.
|
|
legacy = claude_md.read_text()
|
|
assert "Existing instructions." in legacy
|
|
assert _MARKER_START not in legacy
|
|
assert "Build Commands" not in legacy
|
|
|
|
# CLAUDE.local.md now owns the migrated section AND the new one.
|
|
local = (proj.project_path / "CLAUDE.local.md").read_text()
|
|
assert "### Build Commands" in local
|
|
assert "cargo check from src-tauri/" in local
|
|
assert "### Environment" in local
|
|
assert "Use uv" in local
|
|
assert local.count(_MARKER_START) == 1
|
|
|
|
# The migration is surfaced to the user.
|
|
assert any("CLAUDE.md" in w for w in result.warnings)
|
|
|
|
def test_block_only_claude_md_is_removed(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
# CLAUDE.md holds nothing but the Headroom block (no hand-written content).
|
|
claude_md.write_text(
|
|
f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"
|
|
"### Build Commands\n- cargo check\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
result = writer.write(recs, proj, dry_run=False)
|
|
|
|
# The empty husk is deleted rather than left behind as an empty file.
|
|
assert not claude_md.exists()
|
|
local = (proj.project_path / "CLAUDE.local.md").read_text()
|
|
assert "### Build Commands" in local
|
|
assert "### Environment" in local
|
|
assert any("Removed" in w for w in result.warnings)
|
|
|
|
def test_dry_run_block_only_claude_md_not_removed(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
original = (
|
|
f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"
|
|
"### Build Commands\n- cargo check\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
claude_md.write_text(original)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
result = writer.write(recs, proj, dry_run=True)
|
|
|
|
# Dry run leaves the file on disk but still previews the removal.
|
|
assert claude_md.read_text() == original
|
|
assert any("Removed" in w for w in result.warnings)
|
|
|
|
def test_dry_run_migration_writes_nothing(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
original = _legacy_block("Build Commands", "- cargo check")
|
|
claude_md.write_text(original)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
result = writer.write(recs, proj, dry_run=True)
|
|
|
|
# Nothing written on disk, but the warning still fires for the preview.
|
|
assert claude_md.read_text() == original
|
|
assert not (proj.project_path / "CLAUDE.local.md").exists()
|
|
assert any("CLAUDE.md" in w for w in result.warnings)
|
|
|
|
def test_no_migration_when_local_already_owns_block(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
legacy = _legacy_block("Build Commands", "- cargo check")
|
|
claude_md.write_text(legacy)
|
|
local_md = proj.project_path / "CLAUDE.local.md"
|
|
local_md.write_text(
|
|
f"{_MARKER_START}\n## Headroom Learned Patterns\n\n"
|
|
"### Environment\n- prior local note\n\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- fresh note")]
|
|
result = writer.write(recs, proj, dry_run=False)
|
|
|
|
# CLAUDE.md is left untouched (local is already the source of truth).
|
|
assert claude_md.read_text() == legacy
|
|
assert not result.warnings
|
|
local = local_md.read_text()
|
|
assert "fresh note" in local
|
|
assert "prior local note" not in local
|
|
|
|
def test_target_override_skips_migration(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
claude_md = proj.project_path / "CLAUDE.md"
|
|
legacy = _legacy_block("Build Commands", "- cargo check")
|
|
claude_md.write_text(legacy)
|
|
|
|
writer = ClaudeCodeWriter()
|
|
writer.set_context_target("CLAUDE.md")
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
result = writer.write(recs, proj, dry_run=False)
|
|
|
|
# Explicit CLAUDE.md target merges in place, no migration warning.
|
|
assert not result.warnings
|
|
content = claude_md.read_text()
|
|
assert "### Environment" in content
|
|
assert "### Build Commands" in content
|
|
|
|
|
|
class TestHomeDirectoryContext:
|
|
"""The home directory keeps writing to ~/.claude/CLAUDE.md (personal global memory)."""
|
|
|
|
def test_home_dir_writes_global_claude_md(self, tmp_path, monkeypatch):
|
|
fake_home = tmp_path / "home"
|
|
fake_home.mkdir()
|
|
monkeypatch.setattr(Path, "home", classmethod(lambda cls: fake_home))
|
|
|
|
proj = ProjectInfo(
|
|
name="home",
|
|
project_path=fake_home,
|
|
data_path=tmp_path / "data",
|
|
)
|
|
writer = ClaudeCodeWriter()
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
global_md = fake_home / ".claude" / "CLAUDE.md"
|
|
assert global_md.exists()
|
|
assert "Use uv" in global_md.read_text()
|
|
assert not (fake_home / "CLAUDE.local.md").exists()
|
|
|
|
|
|
class TestParsePriorRecommendations:
|
|
"""Direct coverage for _parse_prior_recommendations edge cases."""
|
|
|
|
def test_no_marker_block_returns_empty(self):
|
|
"""A file without any marker block yields no prior recommendations."""
|
|
assert _parse_prior_recommendations("# Project\n\nJust a regular README.\n") == []
|
|
|
|
def test_empty_marker_block_yields_no_recs(self):
|
|
"""A marker block with nothing between the markers yields no recs."""
|
|
content = f"prefix\n{_MARKER_START}\n{_MARKER_END}\nsuffix\n"
|
|
assert _parse_prior_recommendations(content) == []
|
|
|
|
def test_marker_block_with_empty_heading_is_skipped(self):
|
|
"""A stray `### ` (empty heading) inside the block is skipped, not raised."""
|
|
# Leading `### ` with no heading text, followed by a real section.
|
|
content = (
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"### \n"
|
|
"some orphan content\n"
|
|
"\n"
|
|
"### Real Section\n"
|
|
"- real bullet\n"
|
|
"\n"
|
|
f"{_MARKER_END}\n"
|
|
)
|
|
recs = _parse_prior_recommendations(content)
|
|
# Only the real section is parsed; the empty-heading entry is dropped.
|
|
assert len(recs) == 1
|
|
assert recs[0].section == "Real Section"
|
|
assert "real bullet" in recs[0].content
|
|
|
|
|
|
class TestExtractMarkerBlock:
|
|
"""Direct coverage for extract_marker_block."""
|
|
|
|
def test_returns_raw_block_when_present(self):
|
|
"""Marker block is returned verbatim with delimiters, for LLM prompts."""
|
|
content = (
|
|
"# Project README\n\n"
|
|
"Some text.\n\n"
|
|
f"{_MARKER_START}\n"
|
|
"## Headroom Learned Patterns\n"
|
|
"### Environment\n"
|
|
"- Use uv run python\n"
|
|
f"{_MARKER_END}\n"
|
|
"Trailing text.\n"
|
|
)
|
|
block = extract_marker_block(content)
|
|
assert block is not None
|
|
assert block.startswith(_MARKER_START)
|
|
assert block.endswith(_MARKER_END)
|
|
assert "### Environment" in block
|
|
assert "Use uv run python" in block
|
|
assert "Trailing text." not in block
|
|
|
|
def test_returns_none_when_absent(self):
|
|
"""File without any marker delimiters yields None."""
|
|
assert extract_marker_block("# Project\n\nJust a regular README.\n") is None
|
|
|
|
def test_returns_none_when_only_start_marker(self):
|
|
"""Partial/malformed block (start only) yields None — writer expects both delimiters."""
|
|
content = f"prefix\n{_MARKER_START}\n### Something\n- content\n"
|
|
assert extract_marker_block(content) is None
|
|
|
|
def test_returns_empty_block_when_markers_are_adjacent(self):
|
|
"""A block with nothing between the markers is still returned (caller's choice what to do)."""
|
|
content = f"prefix\n{_MARKER_START}\n{_MARKER_END}\nsuffix\n"
|
|
block = extract_marker_block(content)
|
|
assert block is not None
|
|
assert block == f"{_MARKER_START}\n{_MARKER_END}"
|
|
|
|
|
|
class TestEncodingResilience:
|
|
"""Regression tests for #1202 — ``learn --apply`` must not crash merging into
|
|
an existing context file that carries a stray non-UTF-8 byte (e.g. a legacy
|
|
cp1252 em-dash ``0x97``)."""
|
|
|
|
def test_read_text_tolerant_preserves_valid_utf8(self, tmp_path):
|
|
path = tmp_path / "AGENTS.md"
|
|
path.write_text("Use em-dashes — and arrows →.", encoding="utf-8")
|
|
assert _read_text_tolerant(path) == "Use em-dashes — and arrows →."
|
|
|
|
def test_read_text_tolerant_survives_stray_legacy_byte(self, tmp_path):
|
|
# Predominantly valid UTF-8 (genuine em-dash E2 80 94) plus one stray
|
|
# cp1252 em-dash byte (0x97) that strict UTF-8 cannot decode.
|
|
path = tmp_path / "AGENTS.md"
|
|
path.write_bytes("real em-dash — here\n".encode() + b"legacy \x97 byte\n")
|
|
|
|
# The old strict read aborts the whole --apply on that single byte.
|
|
with pytest.raises(UnicodeDecodeError):
|
|
path.read_text(encoding="utf-8")
|
|
|
|
text = _read_text_tolerant(path)
|
|
# Valid UTF-8 content is preserved (no cp1252 "â€" mojibake) and the
|
|
# stray byte is replaced rather than fatal.
|
|
assert "real em-dash — here" in text
|
|
assert "\x97" not in text
|
|
assert "â€" not in text
|
|
|
|
def test_merge_into_file_applies_over_file_with_stray_byte(self, tmp_path):
|
|
path = tmp_path / "AGENTS.md"
|
|
path.write_bytes("# Notes — existing\n".encode() + b"stray \x97 byte\n")
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
merged = _merge_into_file(path, recs)
|
|
|
|
assert "Use uv" in merged
|
|
assert "Notes — existing" in merged
|
|
|
|
def test_read_text_tolerant_normalizes_crlf_and_cr(self, tmp_path):
|
|
path = tmp_path / "AGENTS.md"
|
|
path.write_bytes(b"line1\r\nline2\rline3\n")
|
|
text = _read_text_tolerant(path)
|
|
assert text == "line1\nline2\nline3\n"
|
|
|
|
def test_apply_does_not_accumulate_carriage_returns_on_crlf_file(self, tmp_path):
|
|
proj = _project(tmp_path)
|
|
writer = ClaudeCodeWriter()
|
|
memory_md = proj.data_path / "memory" / "MEMORY.md"
|
|
# Simulate existing Windows CRLF file
|
|
memory_md.write_bytes(b"# Memory Index\r\n\r\n- bullet 1\r\n")
|
|
|
|
recs = [_rec(RecommendationTarget.MEMORY_FILE, "Errors", "- rule 1")]
|
|
writer.write(recs, proj, dry_run=False)
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
raw = memory_md.read_bytes()
|
|
assert b"\r\r" not in raw
|
|
assert raw.count(b"\r") == raw.count(b"\r\n")
|
|
|
|
|
|
def _git(proj: ProjectInfo, *args: str, check: bool = True) -> subprocess.CompletedProcess:
|
|
"""Run git against the test repo, under the isolated config below."""
|
|
return subprocess.run(["git", *args], cwd=proj.project_path, check=check, capture_output=True)
|
|
|
|
|
|
def _git_project(tmp_path: Path) -> ProjectInfo:
|
|
"""A project whose directory is a real git repo."""
|
|
proj = _project(tmp_path)
|
|
_git(proj, "init", "-q")
|
|
return proj
|
|
|
|
|
|
def _exclude(proj: ProjectInfo) -> Path:
|
|
return proj.project_path / ".git" / "info" / "exclude"
|
|
|
|
|
|
def _exclude_entries(proj: ProjectInfo) -> list[str]:
|
|
"""The repo-local exclude rules this PR is responsible for, one per line."""
|
|
path = _exclude(proj)
|
|
if not path.exists():
|
|
return []
|
|
return [line.strip() for line in path.read_text().splitlines() if line.strip()]
|
|
|
|
|
|
def _is_ignored(proj: ProjectInfo, name: str) -> bool:
|
|
return _git(proj, "check-ignore", "-q", "--", name, check=False).returncode == 0
|
|
|
|
|
|
class TestClaudeLocalMdStaysOutOfGit:
|
|
"""CLAUDE.local.md is only personal if git actually ignores it (#1070)."""
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _isolated_git_config(self, monkeypatch, tmp_path):
|
|
"""Decide these tests on the repository alone, on every machine.
|
|
|
|
``git check-ignore`` consults ``core.excludesFile`` from the developer's
|
|
global and system config, and the writer shells out to it too (it skips
|
|
adding a rule when one already covers the file). So a contributor whose
|
|
global ignore lists CLAUDE.md or CLAUDE.local.md saw this suite fail
|
|
while the writer was behaving correctly. Patching the environment rather
|
|
than a helper covers the writer's own subprocess as well as ours.
|
|
"""
|
|
absent = tmp_path / "absent-gitconfig"
|
|
monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(absent))
|
|
monkeypatch.setenv("GIT_CONFIG_SYSTEM", str(absent))
|
|
monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
|
|
|
|
def test_apply_adds_exclude_entry(self, tmp_path):
|
|
proj = _git_project(tmp_path)
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
result = ClaudeCodeWriter().write(recs, proj, dry_run=False)
|
|
|
|
assert "CLAUDE.local.md" in _exclude(proj).read_text()
|
|
# The point is the effect, not the file contents.
|
|
assert _is_ignored(proj, "CLAUDE.local.md")
|
|
assert result.warnings == []
|
|
|
|
def test_second_run_does_not_duplicate_the_entry(self, tmp_path):
|
|
proj = _git_project(tmp_path)
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
writer = ClaudeCodeWriter()
|
|
|
|
writer.write(recs, proj, dry_run=False)
|
|
writer.write(recs, proj, dry_run=False)
|
|
|
|
assert _exclude(proj).read_text().count("CLAUDE.local.md") == 1
|
|
|
|
def test_existing_gitignore_rule_is_left_alone(self, tmp_path):
|
|
proj = _git_project(tmp_path)
|
|
(proj.project_path / ".gitignore").write_text("CLAUDE.local.md\n")
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
ClaudeCodeWriter().write(recs, proj, dry_run=False)
|
|
|
|
assert not _exclude(proj).exists() or "CLAUDE.local.md" not in _exclude(proj).read_text()
|
|
|
|
def test_tracked_file_warns_instead_of_excluding(self, tmp_path):
|
|
proj = _git_project(tmp_path)
|
|
local = proj.project_path / "CLAUDE.local.md"
|
|
local.write_text("# prior\n")
|
|
_git(proj, "add", "CLAUDE.local.md")
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
result = ClaudeCodeWriter().write(recs, proj, dry_run=False)
|
|
|
|
# An ignore rule does nothing for a tracked file, so say so rather than
|
|
# staging a deletion in the user's repo on their behalf.
|
|
assert len(result.warnings) == 1
|
|
assert "git rm --cached CLAUDE.local.md" in result.warnings[0]
|
|
assert not _exclude(proj).exists() or "CLAUDE.local.md" not in _exclude(proj).read_text()
|
|
|
|
def test_dry_run_does_not_touch_exclude(self, tmp_path):
|
|
proj = _git_project(tmp_path)
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
ClaudeCodeWriter().write(recs, proj, dry_run=True)
|
|
|
|
assert not _exclude(proj).exists() or "CLAUDE.local.md" not in _exclude(proj).read_text()
|
|
|
|
def test_explicit_shared_target_is_never_excluded(self, tmp_path):
|
|
proj = _git_project(tmp_path)
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
ClaudeCodeWriter(context_target="CLAUDE.md").write(recs, proj, dry_run=False)
|
|
|
|
# --target CLAUDE.md is a deliberate opt-in to the team-shared file, so
|
|
# the writer must not add a rule for it. Assert the side effect this PR
|
|
# actually owns - the repo's own exclude file - as well as the effect.
|
|
assert "CLAUDE.md" not in _exclude_entries(proj)
|
|
assert not _is_ignored(proj, "CLAUDE.md")
|
|
|
|
def test_outside_a_git_repo_is_a_no_op(self, tmp_path):
|
|
proj = _project(tmp_path) # no git init
|
|
recs = [_rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")]
|
|
|
|
result = ClaudeCodeWriter().write(recs, proj, dry_run=False)
|
|
|
|
assert (proj.project_path / "CLAUDE.local.md").exists()
|
|
assert result.warnings == []
|
|
|
|
|
|
@pytest.mark.windows_newline
|
|
class TestNewlineContract:
|
|
"""Regression guard for #3594 / #3698 — every learn-writer write pins LF.
|
|
|
|
This asserts the *call*, not the artifact, on purpose. ``Path.write_text``
|
|
with ``newline=None`` translates ``\n`` through ``TextIOWrapper``, whose
|
|
translation target is chosen at C-compile time (``#ifdef MS_WINDOWS``), not
|
|
read from ``os.linesep`` at runtime. So on POSIX no fixture can make the
|
|
unpinned call emit CRLF, and every artifact-level assertion here passes
|
|
with the fix reverted. Spying on the kwarg fails the moment a pin is
|
|
dropped, on any platform — which is the property #3698 asked for.
|
|
"""
|
|
|
|
def test_every_learn_writer_write_pins_lf(self, tmp_path, monkeypatch):
|
|
proj = _project(tmp_path)
|
|
context_rec = _rec(RecommendationTarget.CONTEXT_FILE, "Environment", "- Use uv")
|
|
memory_rec = _rec(RecommendationTarget.MEMORY_FILE, "Errors", "- rule 1")
|
|
|
|
# Seed a legacy CLAUDE.md that carries a headroom block *and*
|
|
# hand-written prose, so ClaudeCodeWriter's migration branch (which
|
|
# rewrites the cleaned CLAUDE.md) is exercised alongside the rest.
|
|
(proj.project_path / "CLAUDE.md").write_text(
|
|
_legacy_block("Build Commands", "- cargo check"), encoding="utf-8"
|
|
)
|
|
|
|
calls: list[tuple[Path, str | None]] = []
|
|
original = Path.write_text
|
|
|
|
def spy(self, data, encoding=None, errors=None, newline=None):
|
|
calls.append((self, newline))
|
|
return original(self, data, encoding=encoding, errors=errors, newline=newline)
|
|
|
|
monkeypatch.setattr(Path, "write_text", spy)
|
|
|
|
ClaudeCodeWriter().write([context_rec, memory_rec], proj, dry_run=False)
|
|
CodexWriter().write([context_rec, memory_rec], proj, dry_run=False)
|
|
GeminiWriter().write([context_rec], proj, dry_run=False)
|
|
GrokWriter().write([context_rec], proj, dry_run=False)
|
|
|
|
assert calls, "no writes captured — this test no longer drives the writers"
|
|
unpinned = sorted(str(path) for path, newline in calls if newline != "\n")
|
|
assert not unpinned, f"learn writers wrote without newline='\\n': {unpinned}"
|
|
|
|
# All seven write sites in headroom/learn/writer.py are reached above;
|
|
# if a writer grows a new target, this set fails loudly rather than
|
|
# letting an unguarded write site slip in.
|
|
assert {path.name for path, _ in calls} == {
|
|
"CLAUDE.local.md", # ClaudeCodeWriter context target
|
|
"CLAUDE.md", # legacy-migration rewrite
|
|
"MEMORY.md", # ClaudeCodeWriter memory target
|
|
"AGENTS.md", # CodexWriter context target
|
|
"instructions.md", # CodexWriter memory target
|
|
"GEMINI.md", # GeminiWriter
|
|
"GROK.md", # GrokWriter
|
|
}
|