audit_ingress Namespace Reference

Functions
Set[str]	scan_petsc_options (Iterable[pathlib.Path] paths)
Set[str]	load_manifest (pathlib.Path path)
int	main ()

Variables
	OPTION_RE

Detailed Description

Static ingress audit for PETSc option parsing in setup/io.

This script scans src/setup.c and src/io.c for PetscOptionsGet*/HasName calls,
extracts option flags, and compares them against a maintained manifest.

Function Documentation

scan_petsc_options()

Set[str] audit_ingress.scan_petsc_options

(

Iterable[pathlib.Path]

paths

)

Definition at line 25 of file audit_ingress.py.

def scan_petsc_options(paths: Iterable[pathlib.Path]) -> Set[str]:
    flags: Set[str] = set()
    for path in paths:
        text = path.read_text(encoding="utf-8")
        for match in OPTION_RE.finditer(text):
            flags.add(match.group(1))
    return flags
 
 

Here is the caller graph for this function:

load_manifest()

Set[str] audit_ingress.load_manifest

(

pathlib.Path

path

)

Definition at line 34 of file audit_ingress.py.

def load_manifest(path: pathlib.Path) -> Set[str]:
    data = json.loads(path.read_text(encoding="utf-8"))
    options = data.get("known_petsc_options")
    if not isinstance(options, list):
        raise ValueError("Manifest key 'known_petsc_options' must be a list.")
    bad = [opt for opt in options if not isinstance(opt, str) or not opt.startswith("-")]
    if bad:
        raise ValueError(f"Manifest has invalid option entries: {bad}")
    return set(options)
 
 

Here is the caller graph for this function:

main()

int audit_ingress.main

(

)

Definition at line 45 of file audit_ingress.py.

def main() -> int:
    parser = argparse.ArgumentParser(description="Audit PETSc option ingress against manifest.")
    parser.add_argument(
        "--manifest",
        default="scripts/audit_ingress_manifest.json",
        help="Path to ingress manifest JSON.",
    )
    parser.add_argument(
        "--show-scanned",
        action="store_true",
        help="Print scanned option list before comparison.",
    )
    args = parser.parse_args()
 
    repo_root = pathlib.Path(__file__).resolve().parents[1]
    manifest_path = (repo_root / args.manifest).resolve()
    scan_paths = [repo_root / "src/setup.c", repo_root / "src/io.c"]
 
    if not manifest_path.exists():
        print(f"[ERROR] Manifest not found: {manifest_path}", file=sys.stderr)
        return 2
 
    scanned = scan_petsc_options(scan_paths)
    expected = load_manifest(manifest_path)
 
    missing_in_manifest = sorted(scanned - expected)
    stale_in_manifest = sorted(expected - scanned)
 
    if args.show_scanned:
        print("[INFO] Scanned PETSc options:")
        for flag in sorted(scanned):
            print(flag)
        print("")
 
    print(f"[INFO] Scanned options: {len(scanned)}")
    print(f"[INFO] Manifest options: {len(expected)}")
 
    if missing_in_manifest:
        print("[ERROR] New PETSc ingress options missing in manifest:")
        for flag in missing_in_manifest:
            print(f"  - {flag}")
 
    if stale_in_manifest:
        print("[ERROR] Manifest options no longer present in setup/io scan:")
        for flag in stale_in_manifest:
            print(f"  - {flag}")
 
    if missing_in_manifest or stale_in_manifest:
        print(
            "[FAIL] Ingress drift detected. Update scripts/audit_ingress_manifest.json and docs mapping.",
            file=sys.stderr,
        )
        return 1
 
    print("[OK] Ingress manifest matches setup/io PETSc option scan.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

OPTION_RE

audit_ingress.OPTION_RE

Initial value:

=  re.compile(
    r'PetscOptions(?:Get(?:Int|Real|Bool|String|IntArray|RealArray)|HasName)\s*'
    r'\‍(\s*NULL\s*,\s*NULL\s*,\s*"(-[^"]+)"'
)

Definition at line 19 of file audit_ingress.py.