Files

71 lines
2.9 KiB
Python

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-only
"""List intentional compatibility changes documented in source comments."""
import argparse
from pathlib import Path
import re
from check_public_tree import cpp_exclusions
MARKER = "OpenBMH deviates from the original:"
def render(root):
entries = []
for path in sorted((root / "src").rglob("*")):
if path.suffix not in {".cpp", ".hpp", ".h", ".c", ".inc"} or "third_party" in path.parts:
continue
text = path.read_text(encoding="utf-8")
spans = list(cpp_exclusions(text))
at = 0
while at < len(spans):
start, end, kind = spans[at]
at += 1
if kind != "comment":
continue
while at < len(spans):
following, finish, next_kind = spans[at]
between = text[end:following]
if next_kind != "comment" or between.strip() or between.count("\n") > 1:
break
end = finish
at += 1
content = text[start:end]
if MARKER not in content:
continue
relative = path.relative_to(root).as_posix()
for declaration in content.split(MARKER)[1:]:
description = " ".join(line.strip().removeprefix("//").lstrip("* ")
for line in declaration.removesuffix("*/").splitlines())
# The first complete sentence is the declared change. Adjacent
# comments can also describe implementation details or examples.
description = re.split(r"(?<=[.!?])(?:\s|$)", description, maxsplit=1)[0]
if (relative, description) not in entries:
entries.append((relative, description))
lines = ["# Intentional differences from the original", "",
"Generated from source comment markers by `tools/public_release/collect_differences.py`.", "",
"See [Compatibility decisions](COMPATIBILITY.md) for the overall policy. These entries",
"describe deliberate changes; they are not a list of every known compatibility limit.", ""]
for path, description in entries:
lines.append(f"- [{path}](../{path}): {description}")
return "\n".join(lines) + "\n"
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2])
parser.add_argument("--check", action="store_true")
args = parser.parse_args()
destination = args.root / "docs" / "DIFFERENCES.md"
expected = render(args.root)
if args.check:
if not destination.is_file() or destination.read_text(encoding="utf-8") != expected:
parser.exit(1, "Differences catalogue needs regeneration\n")
else:
destination.write_text(expected, encoding="utf-8")
if __name__ == "__main__":
main()