The new modules_poc/private_headers.py should:

• almost certainly be written in python and use typer for arg parsing (like the merger does today)
• allow the user to specify any/all of a (glob, module, code owner team) to filter which files will be considered/modified. Use mod_for_file and teams_for_file from mod_mapping.py to do this.
• modify the source to add the #include <mongo/util/modules.h> line above the first #include or after #pragma once if there are no includes
• look for any _forTest functions that will implicitly become FILE_PRIVATE that are used from outside their file family, and print their loc and display_name  along with a message about that and suggesting that they should add MONGO_MOD_PRIVATE to allow their continued use within the module.
• when the private file is a blah/blah/src/mongo/blah/foo_gen.h map it back to a src/mongo/blah/foo.idl file and add a mod_visibility: private line in the top-level global: key creating it if it doesn't exist. To minimize changes to the idl files (in particular, preserving comments) we should either make the edit textually (shouldn't be too hard) or use a lib like ruamel.yaml that can make edits while preserving formatting and comments. My gut says it will be better to try doing it textually first and only bring in a new lib if we run into some complexity I didn't think of.
• print a message saying "WARNING: This tool marks all files where there are no currently detected external usages. That does not necessarily mean that it is intended to be private. A human should review to ensure that this matches intent."

See modules_poc/mod_diff.py for code that accesses the parsed decls from a script. Search merge_decls.py for file_private to see how we define file families.