71 lines
2.9 KiB
Python
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()
|