From the review on PR #1: #1 (comment)
Every read in the package is read_text(encoding="utf-8") with no errors=, and english_diff decodes git's output the same way. Three defects follow.
One non-UTF-8 byte takes the gate down. A stray latin-1 byte in one translation raises UnicodeDecodeError at exit 1 — the same status the gate uses for "translations are stale" — so the workflow reports a translation failure for a file-encoding problem. Worse: bad bytes in a historical blob referenced by a stamp crash --comment for a page that is clean in the working tree.
CRLF pages diff as whole-file rewrites. subprocess.run(..., text=True) translates CRLF to LF in git cat-file output while write_text writes LF, so the temp file differs from the blob by line endings and git diff --no-index reports every line changed. A one-line edit renders as a full-page rewrite, which is also what inflates bodies into the broken fallback (#1). When the change was line endings only, the round trip makes the files identical, the diff comes back empty, and the false fetch-depth notice fires.
A BOM turns the prescribed remedy into corruption. A UTF-8 BOM defeats text.startswith("---\n") in both stamp_of and restamp. The gate calls the page unstamped and tells the author to run stamp-translation, which then prepends a second frontmatter block — demoting the original metadata, including its genuinely stale stamp, into the body where mkdocs renders it as visible text, and losing the page title. Red → apply the documented fix → green → broken page. Verified end to end.
Fix: work in bytes in english_diff (write_bytes, decode the diff separately with errors="replace"); strip a leading BOM before the frontmatter checks in both modules and refuse rather than prepend when the first non-BOM bytes look like frontmatter that failed to parse; pass errors="replace" on reads that only feed classification and name the affected page.
Related: stamp_of raises AttributeError on non-mapping frontmatter and yaml.ScannerError on unscannable frontmatter, both as tracebacks. Nine translators on unknown toolchains produce all of these.
From the review on PR #1: #1 (comment)
Every read in the package is
read_text(encoding="utf-8")with noerrors=, andenglish_diffdecodes git's output the same way. Three defects follow.One non-UTF-8 byte takes the gate down. A stray latin-1 byte in one translation raises
UnicodeDecodeErrorat exit 1 — the same status the gate uses for "translations are stale" — so the workflow reports a translation failure for a file-encoding problem. Worse: bad bytes in a historical blob referenced by a stamp crash--commentfor a page that is clean in the working tree.CRLF pages diff as whole-file rewrites.
subprocess.run(..., text=True)translates CRLF to LF ingit cat-fileoutput whilewrite_textwrites LF, so the temp file differs from the blob by line endings andgit diff --no-indexreports every line changed. A one-line edit renders as a full-page rewrite, which is also what inflates bodies into the broken fallback (#1). When the change was line endings only, the round trip makes the files identical, the diff comes back empty, and the false fetch-depth notice fires.A BOM turns the prescribed remedy into corruption. A UTF-8 BOM defeats
text.startswith("---\n")in bothstamp_ofandrestamp. The gate calls the pageunstampedand tells the author to runstamp-translation, which then prepends a second frontmatter block — demoting the original metadata, including its genuinely stale stamp, into the body where mkdocs renders it as visible text, and losing the page title. Red → apply the documented fix → green → broken page. Verified end to end.Fix: work in bytes in
english_diff(write_bytes, decode the diff separately witherrors="replace"); strip a leading BOM before the frontmatter checks in both modules and refuse rather than prepend when the first non-BOM bytes look like frontmatter that failed to parse; passerrors="replace"on reads that only feed classification and name the affected page.Related:
stamp_ofraisesAttributeErroron non-mapping frontmatter andyaml.ScannerErroron unscannable frontmatter, both as tracebacks. Nine translators on unknown toolchains produce all of these.