{"record":{"id":"92ca7f9a49ffd609","repo":"Stirling-Tools/Stirling-PDF","slug":"path-refusing-to-sort-sorting-would-change-the","errorCode":null,"errorMessage":"{path}: refusing to sort, sorting would change the file's contents","messagePattern":"(.+?): refusing to sort, sorting would change the file's contents","errorType":"exception","errorClass":"SortError","httpStatus":null,"severity":"error","filePath":"scripts/pre-commit/sort_locale_toml.py","lineNumber":59,"sourceCode":"\ndef sort_file(path: str, fix: bool) -> bool:\n    \"\"\"Rewrite one file if `fix`; return whether it was not already sorted.\"\"\"\n    text = Path(path).read_text(encoding=\"utf-8\")\n    try:\n        original = tomllib.loads(text)\n    except tomllib.TOMLDecodeError as exc:\n        raise SortError(f\"{path}: invalid TOML: {exc}\") from exc\n\n    expected = tomli_w.dumps(ordered(original))\n    if expected == text:\n        return False\n\n    try:\n        reordered = tomllib.loads(expected)\n    except tomllib.TOMLDecodeError as exc:\n        raise SortError(f\"{path}: refusing to sort, the sorted output is not valid TOML: {exc}\") from exc\n    if reordered != original:\n        raise SortError(f\"{path}: refusing to sort, sorting would change the file's contents\")\n\n    if fix:\n        Path(path).write_text(expected, encoding=\"utf-8\")\n    return True\n\n\ndef main() -> int:\n    args = sys.argv[1:]\n    fix = \"--fix\" in args\n    pathspecs = [a for a in args if a != \"--fix\"]\n\n    offenders: list[str] = []\n    errors: list[str] = []\n    for path in tracked_files(pathspecs):\n        try:\n            if sort_file(path, fix):\n                offenders.append(path)\n        except SortError as exc:","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/Stirling-Tools/Stirling-PDF/blob/9ef20dcab80b85041912f045e17a6aea1d08f969/scripts/pre-commit/sort_locale_toml.py#L41-L77","documentation":"The second round-trip guard at sort_locale_toml.py:58: after re-parsing the sorted output, the resulting table must be deeply equal to the original. Python dict equality ignores insertion order, so this fires only when re-serialization changed the data model itself, not merely key order. The hook refuses to write because sorting would silently alter the file's meaning. It catches sort-induced semantic drift from TOML constructs whose canonical form under tomli_w differs from the parsed structure.","triggerScenarios":"A TOML feature whose canonical form under tomli_w differs from the parsed structure -- array-of-tables, inline tables expanded to standard tables, dotted keys normalized -- so the re-parsed dict no longer equals the original; case-insensitive sort reordering keys whose tomli_w resolution differs.","commonSituations":"Locale files mixing inline and standard tables for the same data; a tomli_w upgrade changes how it emits a construct; a file with keys differing only by case that the str.lower sort reorders.","solutions":["Manually sort that file's keys in your editor and exclude it from the auto-sort path","Reduce the file to plain key/value pairs and standard tables so the round-trip is stable","Add a temporary debug print of `original` vs `reordered` to find exactly which key's value model changed, then simplify that construct"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import tomllib, tomli_w\nfrom pathlib import Path\n\ndef sort_preserves_semantics(path: str) -> bool:\n    text = Path(path).read_text(encoding=\"utf-8\")\n    try:\n        original = tomllib.loads(text)\n        reparsed = tomllib.loads(tomli_w.dumps(original))\n    except tomllib.TOMLDecodeError:\n        return False\n    return reparsed == original","typeGuard":null,"tryCatchPattern":"try:\n    sort_file(path, fix)\nexcept SortError as exc:\n    errors.append(str(exc))","preventionTips":["Avoid mixing inline tables and standard tables for the same data in locale files","When a file fails this check, diff `original` vs `reordered` to localize the semantic drift before editing","Prefer plain tables over arrays-of-tables in files covered by the sort hook"],"tags":["toml","pre-commit","sorting","semantics"],"backgroundTag":null,"analyzedSha":"9ef20dcab80b85041912f045e17a6aea1d08f969","analyzedAt":"2026-08-13T22:11:39.827Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}