Keep report output explicit in a read-only project scanner
Also published in our Blogger archive.
Direct answer
A scan remains read-only only when its report destination is deliberately outside the selected project tree. The temporary fixture writes report.md beside the project directory, then asserts that the project still contains only its original README. This prevents a second scan from discovering a report created by the first one.
The edge case is output feedback: a tool that defaults to writing inside the target can change its own filename count, report a generated file as source evidence, or overwrite a user artifact. Treat destination as an explicit caller choice and keep target traversal independent of it.
The example does not handle an existing destination, create nested output parents, or address filesystem permissions. Those are separate output rules. It establishes the more basic guarantee that observing the project does not add a file to the project.
Complete example
from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory() as directory:
workspace = Path(directory)
project = workspace / "project"
project.mkdir()
(project / "README.md").write_text("source", encoding="utf-8")
destination = workspace / "report.md"
destination.write_text("# Hygiene report\n", encoding="utf-8")
assert sorted(item.name for item in project.iterdir()) == ["README.md"]
assert destination.read_text(encoding="utf-8") == "# Hygiene report\n"
print("project_modified=no report_written=yes")Expected stdout:
project_modified=no report_written=yesSources
Prepared with AI assistance. The example uses synthetic data; its stated limits apply.