audit_user_facing_reporting Namespace Reference

Functions
str	strip_c_comments (str text)
	Replace C comments while preserving source line positions.
list[str]	audit_direct_c_output ()
	Return raw C console emissions outside their approved rendering modules.
list[str]	require_fragments (Path path, tuple[str,...] fragments, str surface)
	Return missing reporting-contract fragments for one user-facing surface.
list[str]	audit_cli_contract (dict contract)
	Verify that every declared CLI command has a parser, dispatch handler, and contextual message.
int	main ()
	Audit C banner, CLI summaries, and direct-output routing.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	SRC_DIR = REPO_ROOT / "src"
dict	ALLOWED_DIRECT_C_OUTPUT
tuple	BANNER_REQUIRED
str	CONTRACT_PATH = REPO_ROOT / "tests" / "tooling" / "user_facing_reporting_contract.json"
tuple	CLI_REQUIRED

Detailed Description

Validate the repository's option-aware user-facing reporting contract.

Function Documentation

strip_c_comments()

str audit_user_facing_reporting.strip_c_comments

(

str

text

)

Replace C comments while preserving source line positions.

Parameters

[in]

text

C source text to normalize.

Returns

Source text with comments replaced by whitespace/newlines.

Definition at line 38 of file audit_user_facing_reporting.py.

def strip_c_comments(text: str) -> str:
    """!
    @brief Replace C comments while preserving source line positions.
    @param[in] text C source text to normalize.
    @return Source text with comments replaced by whitespace/newlines.
    """
 
    text = re.sub(r"/\*.*?\*/", lambda match: "\n" * match.group(0).count("\n"), text, flags=re.DOTALL)
    return re.sub(r"//[^\n]*", "", text)
 
 

Here is the caller graph for this function:

audit_direct_c_output()

list[str] audit_user_facing_reporting.audit_direct_c_output

(

)

Return raw C console emissions outside their approved rendering modules.

Returns

Human-readable findings for every disallowed emission.

Definition at line 49 of file audit_user_facing_reporting.py.

def audit_direct_c_output() -> list[str]:
    """!
    @brief Return raw C console emissions outside their approved rendering modules.
    @return Human-readable findings for every disallowed emission.
    """
 
    findings: list[str] = []
    pattern = re.compile(r"\b(?:PetscPrintf|PetscSynchronizedPrintf|printf)\s*\‍(")
    for path in sorted(SRC_DIR.glob("*.c")):
        if path.name in ALLOWED_DIRECT_C_OUTPUT:
            continue
        stripped = strip_c_comments(path.read_text(encoding="utf-8", errors="ignore"))
        for match in pattern.finditer(stripped):
            line = stripped.count("\n", 0, match.start()) + 1
            findings.append(
                f"{path.relative_to(REPO_ROOT)}:{line}: raw console output must use the logging policy "
                "or be moved to an approved reporting surface."
            )
    return findings
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

require_fragments()

list[str] audit_user_facing_reporting.require_fragments	(	Path	path,
		tuple[str, ...]	fragments,
		str	surface
	)

Return missing reporting-contract fragments for one user-facing surface.

Parameters

[in]	path	Source file containing the surface.
[in]	fragments	Required literal contract fragments.
[in]	surface	Human-readable surface name for failures.

Returns

Findings for missing fragments.

Definition at line 70 of file audit_user_facing_reporting.py.

def require_fragments(path: Path, fragments: tuple[str, ...], surface: str) -> list[str]:
    """!
    @brief Return missing reporting-contract fragments for one user-facing surface.
    @param[in] path Source file containing the surface.
    @param[in] fragments Required literal contract fragments.
    @param[in] surface Human-readable surface name for failures.
    @return Findings for missing fragments.
    """
 
    text = path.read_text(encoding="utf-8")
    return [f"{surface}: missing required option-aware reporting fragment {fragment!r}."
            for fragment in fragments if fragment not in text]
 
 

Here is the caller graph for this function:

audit_cli_contract()

list[str] audit_user_facing_reporting.audit_cli_contract

(

dict

contract

)

Verify that every declared CLI command has a parser, dispatch handler, and contextual message.

Parameters

[in]

contract

Parsed user-facing reporting contract mapping.

Returns

Findings for missing CLI command-reporting contract elements.

Definition at line 84 of file audit_user_facing_reporting.py.

def audit_cli_contract(contract: dict) -> list[str]:
    """!
    @brief Verify that every declared CLI command has a parser, dispatch handler, and contextual message.
    @param[in] contract Parsed user-facing reporting contract mapping.
    @return Findings for missing CLI command-reporting contract elements.
    """
 
    cli_text = (REPO_ROOT / "picurv_cli" / "cli.py").read_text(encoding="utf-8")
    core_text = (REPO_ROOT / "picurv_cli" / "core.py").read_text(encoding="utf-8")
    findings: list[str] = []
    for command, entry in contract["cli_commands"].items():
        for field, text, surface in (
            ("parser", cli_text, "CLI parser"),
            ("handler", core_text, "CLI handler"),
            ("context", cli_text + core_text, "CLI context"),
        ):
            if entry[field] not in text:
                findings.append(f"{surface} for '{command}': missing contract fragment {entry[field]!r}.")
    return findings
 
 

Here is the caller graph for this function:

main()

int audit_user_facing_reporting.main

(

)

Audit C banner, CLI summaries, and direct-output routing.

Returns

Process status code.

Definition at line 105 of file audit_user_facing_reporting.py.

def main() -> int:
    """!
    @brief Audit C banner, CLI summaries, and direct-output routing.
    @return Process status code.
    """
 
    findings = audit_direct_c_output()
    contract = json.loads(CONTRACT_PATH.read_text(encoding="utf-8"))
    findings.extend(require_fragments(
        REPO_ROOT / contract["banner"]["source"], tuple(contract["banner"]["required_fragments"]), "C startup banner"
    ))
    findings.extend(require_fragments(REPO_ROOT / "picurv_cli" / "core.py", CLI_REQUIRED, "Python CLI/summarize"))
    findings.extend(audit_cli_contract(contract))
    if findings:
        print("\n".join(findings), file=sys.stderr)
        return 1
    print("User-facing reporting audit passed.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

audit_user_facing_reporting.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 12 of file audit_user_facing_reporting.py.

SRC_DIR

str audit_user_facing_reporting.SRC_DIR = REPO_ROOT / "src"

Definition at line 13 of file audit_user_facing_reporting.py.

ALLOWED_DIRECT_C_OUTPUT

dict audit_user_facing_reporting.ALLOWED_DIRECT_C_OUTPUT

Initial value:

=  {
    "io.c",             # Rank-zero effective-configuration banner.
    "logging.c",        # Logging and diagnostic rendering sinks.
    "setup.c",          # Bootstrap warnings before logging is configured.
    "runloop.c",        # Progress-bar line control.
    "postprocessor.c",  # Progress-bar line control.
    "momentumsolvers.c",  # Unconditional convergence warnings.
}

Definition at line 14 of file audit_user_facing_reporting.py.

BANNER_REQUIRED

tuple audit_user_facing_reporting.BANNER_REQUIRED

Initial value:

=  (
    "Momentum Equation Solver",
    "Initial Pseudo-CFL (Courant)",
    "Newton-Krylov PETSc Controls",
    "Pseudo-Time Controller      : NOT APPLICABLE",
    "Console Log Level",
    "Profiling Timestep Output",
    "Runtime Memory Log",
    "Solution Convergence Mode",
)

Definition at line 22 of file audit_user_facing_reporting.py.

CONTRACT_PATH

str audit_user_facing_reporting.CONTRACT_PATH = REPO_ROOT / "tests" / "tooling" / "user_facing_reporting_contract.json"

Definition at line 32 of file audit_user_facing_reporting.py.

CLI_REQUIRED

tuple audit_user_facing_reporting.CLI_REQUIRED

Initial value:

=  ("Momentum Solver: Dual Time Picard Jameson RK", "Momentum Solver: Newton Krylov",
                "Momentum Solver: Explicit RK (no pseudo-time controller)",
                "Dual-Time Pseudo-Time Controls", "Newton--Krylov Controls")

Definition at line 33 of file audit_user_facing_reporting.py.