Write a reproducible investigation report
Publish structured findings and collection errors without accumulating stale rows.
Reports are another interface
A useful report preserves source IDs, explains why a rule matched, and makes collection errors visible. CSV works well for rows and JSON for a structured summary. Use csv.DictWriter so commas, quotes, Unicode and embedded newlines are escaped correctly.
Open CSV files with UTF-8 and newline="". Write a header even when there are no rows. An empty report with a schema can still be read by the next tool; a missing file leaves the reader guessing whether generation succeeded.
Repeated runs should replace earlier results
Use write mode for each report instead of append mode. Sort rows by documented keys so input order does not change the review output. A successful second run with fewer findings must remove old rows, not leave yesterday's evidence mixed into today's report.
The summary has separate finding and error counts and an evidence_complete boolean. Zero findings with errors is an incomplete investigation, not a clean bill of health. Keep that difference visible when you share the result.
These training reports contain controlled fictional data. CSV quoting protects the file structure; it does not make arbitrary exported text safe to execute as spreadsheet formulas. Treat report cells as data when opening exports in other applications. Our checks parse the CSV as records and inspect values rather than requiring one formatting style.
import csv, io
output = io.StringIO(newline="")
writer = csv.DictWriter(output, fieldnames=["source_id", "detail"])
writer.writeheader()
writer.writerow({"source_id":"e1", "detail":'Owner said "review, please"'})
print(output.getvalue())
Put it into practice.
Define write_report(findings, errors, directory). Create the directory and replace findings.csv (rule,source_id,detail), errors.csv (source,line,reason), and summary.json. Write CSV headers for empty results. Sort findings by (rule, source_id, detail), errors by (source, numeric line, reason). Use UTF-8 and proper CSV quoting. Return and save {findings: count, errors: count, evidence_complete: not errors}. Preserve input records. Repeated runs must remove old rows.
See an explained solution
import csv, json
from pathlib import Path
def write_report(findings, errors, directory):
output = Path(directory)
output.mkdir(parents=True, exist_ok=True)
with (output / "findings.csv").open("w", encoding="utf-8", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=["rule", "source_id", "detail"])
writer.writeheader()
writer.writerows(sorted(findings, key=lambda row: (row["rule"], row["source_id"], row["detail"])))
with (output / "errors.csv").open("w", encoding="utf-8", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=["source", "line", "reason"])
writer.writeheader()
writer.writerows(sorted(errors, key=lambda row: (row["source"], row["line"], row["reason"])))
summary = {"findings": len(findings), "errors": len(errors), "evidence_complete": not errors}
(output / "summary.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2)+"\n", encoding="utf-8")
return summary
Fixed schemas and sorted records make reports repeatable. Separate error counts preserve uncertainty, and write mode prevents stale findings from surviving a rerun.