audit_generic_expansion Namespace Reference

Functions
dict	load_contract ()
	Load the forbidden-signature contract.
	iter_markdown (dict contract)
	Yield every repository Markdown file inside the contract's scan scope.
str	normalize (str text)
	Collapse whitespace so formatting changes cannot hide an exact template copy.
list[str]	scan (dict contract)
	Collect every forbidden-signature hit in the Markdown corpus.
int	main ()
	Fail when generic expansion debris is present in the Markdown corpus.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	CONTRACT_PATH = REPO_ROOT / "tests" / "tooling" / "generic_expansion_contract.json"

Detailed Description

Reject generic documentation-expansion debris anywhere in the repository Markdown corpus.

Function Documentation

load_contract()

dict audit_generic_expansion.load_contract

(

)

Load the forbidden-signature contract.

Returns

Parsed contract mapping.

Definition at line 15 of file audit_generic_expansion.py.

def load_contract() -> dict:
    """!
    @brief Load the forbidden-signature contract.
    @return Parsed contract mapping.
    """
    return json.loads(CONTRACT_PATH.read_text(encoding="utf-8"))
 
 

Here is the caller graph for this function:

iter_markdown()

audit_generic_expansion.iter_markdown

(

dict

contract

)

Yield every repository Markdown file inside the contract's scan scope.

Parameters

[in]

contract

Parsed contract mapping.

Returns

Generator of Markdown paths.

Definition at line 23 of file audit_generic_expansion.py.

def iter_markdown(contract: dict):
    """!
    @brief Yield every repository Markdown file inside the contract's scan scope.
    @param[in] contract Parsed contract mapping.
    @return Generator of Markdown paths.
    """
    excluded = set(contract["scan"]["exclude_dirs"])
    for path in sorted(REPO_ROOT.rglob("*.md")):
        if excluded.intersection(path.relative_to(REPO_ROOT).parts):
            continue
        yield path
 
 

Here is the caller graph for this function:

normalize()

str audit_generic_expansion.normalize

(

str

text

)

Collapse whitespace so formatting changes cannot hide an exact template copy.

Parameters

[in]

text

Raw file text.

Returns

Whitespace-normalized text.

Definition at line 36 of file audit_generic_expansion.py.

def normalize(text: str) -> str:
    """!
    @brief Collapse whitespace so formatting changes cannot hide an exact template copy.
    @param[in] text Raw file text.
    @return Whitespace-normalized text.
    """
    return " ".join(text.split())
 
 

Here is the caller graph for this function:

scan()

list[str] audit_generic_expansion.scan

(

dict

contract

)

Collect every forbidden-signature hit in the Markdown corpus.

Parameters

[in]

contract

Parsed contract mapping.

Returns

Human-readable violation lines.

Definition at line 45 of file audit_generic_expansion.py.

def scan(contract: dict) -> list[str]:
    """!
    @brief Collect every forbidden-signature hit in the Markdown corpus.
    @param[in] contract Parsed contract mapping.
    @return Human-readable violation lines.
    """
    signatures = [
        ("marker", contract["forbidden_markers"]),
        ("heading", contract["forbidden_headings"]),
        ("fragment", contract["forbidden_fragments"]),
    ]
    violations: list[str] = []
    for path in iter_markdown(contract):
        text = path.read_text(encoding="utf-8", errors="replace")
        collapsed = normalize(text)
        relative = path.relative_to(REPO_ROOT)
        for kind, patterns in signatures:
            for pattern in patterns:
                if pattern in text or normalize(pattern) in collapsed:
                    violations.append(f"{relative}: forbidden {kind}: {pattern[:72]}")
    return violations
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

main()

int audit_generic_expansion.main

(

)

Fail when generic expansion debris is present in the Markdown corpus.

Returns

Process status code.

Definition at line 68 of file audit_generic_expansion.py.

def main() -> int:
    """!
    @brief Fail when generic expansion debris is present in the Markdown corpus.
    @return Process status code.
    """
    contract = load_contract()
    violations = scan(contract)
    if violations:
        print("Generic documentation-expansion debris detected:", file=sys.stderr)
        for violation in violations:
            print(f"  {violation}", file=sys.stderr)
        print(
            "\nThese signatures mark uniform agent-generated filler. Replace them with "
            "guidance specific to this page's subject, or remove the section.",
            file=sys.stderr,
        )
        return 1
    print(f"Generic-expansion audit passed: {sum(1 for _ in iter_markdown(contract))} Markdown files clean.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

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

Definition at line 11 of file audit_generic_expansion.py.

CONTRACT_PATH

str audit_generic_expansion.CONTRACT_PATH = REPO_ROOT / "tests" / "tooling" / "generic_expansion_contract.json"

Definition at line 12 of file audit_generic_expansion.py.