add a script to analyze git history for a repo (#1120)

tools/stronghold/bin/analyze-history

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+
+"""Runs the API backward compatibility check on commits in the repo.
+
+This gives an indication of what the tool would have caught if applied
+to the commit before integrated into trunk.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+import os
+import pathlib
+import pprint
+import sys
+
+import api.compatibility
+import api.git
+
+
+def main(argv: Sequence[str]) -> None:
+    parser = argparse.ArgumentParser(
+        prog=argv[0],
+        description=__doc__,
+        # Our description docstring has newlines we wish to preserve.
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument('repo', type=pathlib.Path, help='The path to the repository.')
+
+    parser.add_argument(
+        '--commit_id',
+        default='HEAD',
+        type=str,
+        help='Which commit id to start with.',
+    )
+    parser.add_argument(
+        '--limit',
+        default=1,
+        type=int,
+        help=(
+            'If greater than 1, how many commits to inspect, following parents from '
+            '--commit_id.'
+        ),
+    )
+
+    args = parser.parse_args(argv[1:])
+
+    repo = api.git.Repository(args.repo)
+    commit_id = args.commit_id
+
+    for i in range(args.limit):
+        violations_by_file, commit_id = api.compatibility.check_commit(repo, commit_id)
+        if len(violations_by_file) != 0:
+            print('Commit:', commit_id)
+            for file, violations in violations_by_file.items():
+                print('File:', os.fspath(file))
+                pprint.pp(violations)
+                print()
+
+        # Recurse with parent.
+        commit_id += '~'
+
+
+if __name__ == "__main__":
+    main(sys.argv)