Initial commit of the common trick header dev branch

[jman025]

Refs #46

[ninotarantino]

This is looking pretty good, just a few more edge cases we'll want to fix.

Some general script comments:

• Instead of specifying a file with -f, can we have the filename be a positional argument? bin/cml_common_trick_header.py <args> filename.
• Along those lines, let's have the script handle multiple files at once. My goal is to essentially run git ls-files '*.hh' '*.cc' and pipe the output to the script with the -c flag as part of our CI pipeline.
• Minor nit, but since the script modifies files I think it should be named something with a verb, like apply_cml_trick_header_format.py or something.
• Right now the script warns on not having PYTHON_MODULE in the Trick header for source files but that directive only applies to headers. We'll want it to check that the file it's processing is either a .h or .hh file for the python module check.
• Looks like the script doesn't recognize the ICG: directive right now. From the Trick documentation it can be [ICG: (No|Nocomment)].

The purpose section is placed within a second set of parenthesis but it should just stay at one. So I'm seeing the script convert

PURPOSE: (some purpose)

to

PURPOSE:
(
 (some purpose)  <-- should be no parenthesis here
)

I'm also seeing the script choke on Trick headers that use a cascading '*', like the following:

/*
 * PURPOSE: (test)
 *
 * LIBRARY DEPENDENCY: 
 *  (
 *   (../src/test.cc)
 *  )
 * /

In cases like that, it actually removes everything except the purpose field in the formatted output. This may end up being a nightmare to fix so just let me know if it's feasible to handle this case or not. Realistically, headers formatted this way will already fail our formatting check so the script does its main job, and just from looking around randomly I don't believe this is a common pattern in the repo anyways.

For long lines, let's add one more indent when wrapping text just for visual clarity. So for the following header:

/*
   PURPOSE: (Test)
  
   LIBRARY_DEPENDENCY:
    (
     (../src/test.cc)
    )
  
   PROGRAMMERS:
    (
     ((Nino Tarantino) (CACI) (July 2026) (This is a very long comment that should get wrapped at 80 characters.))
    )
 */

The programmers section ends up like

PROGRAMMERS:
    (
     ((Nino Tarantino) (CACI) (July 2026) (This is a very long comment that
     should get wrapped at 80 characters.))
    )

But I think it would look clearer if the line break was indented to visually separate a continued line from a new entry. Especially if there ends up being multiple entries:

PROGRAMMERS:
    (
     ((Nino Tarantino) (CACI) (July 2026) (This is a very long comment that
       should get wrapped at 80 characters.))  <-- I think one space of indent would look fine, too
     ((Another contributor) (Company) (July 2026) (Another))
    )

[ninotarantino]

Should've left that previous comment as part of the official GitHub review, whoops.

[coveralls]

coverage: 90.214%. remained the same — 40_common_trick_header_dev into main

[ninotarantino]

Just a couple minor changes to the script itself and then I say this is ready to merge. Go ahead and update the initial comment in the description with a brief overview of the changes as well. After those updates are pushed I'll approve this.

[ninotarantino]

Can we use an enum or some sort of named variable here? It would also make some spots further down in the code easier to read/maintain. Then instead of return -1 we'd have something like return EXIT_CODE_LINE_TOO_LONG.

[ninotarantino]

General comment for this file, let's add docstrings to each function. Doesn't have to be too fancy but it'll be good for maintenance.

Suggested change

	def check_inline_open_parens(text):
	def check_inline_open_parens(text):
	"""
	Returns true if a source file line contains a valid Trick header field followed
	by a colon, such as `PURPOSE:`.
	Inputs:
	--------
	text : str
	A line of text from a source file
	"""