audit_path_literals Namespace Reference

Functions
list	tracked_markdown ()
	Markdown files the current commit carries.
bool	in_code_block (list lines, int index)
	Whether a line sits inside a fenced code block.
int	main ()
	Fail when narrative prose hardcodes a run-relative path.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	TOPOLOGY = REPO_ROOT / "tests" / "tooling" / "artifact_topology.json"
dict	SKIP_DIRS = {".git", "docs_build", "obj", "bin", "stubs", "runs", "studies", "__pycache__", ".pytest_cache"}
dict	HISTORICAL = {"docs/CHANGELOG.md"}
str	RUN_OWNED = "config|logs|output|scheduler|visualization|checkpoints"
	MANAGED
	PLACEHOLDER_ROOT
	BARE_PREFIX
	REPO_OWNED = re.compile(r"<repo>/[A-Za-z0-9_][A-Za-z0-9_./*<>-]*")
	WORKSPACE_OWNED = re.compile(r"<workspace>/[A-Za-z0-9_][A-Za-z0-9_./*<>-]*")
tuple	REPO_CONFIG_SUBDIRS
	NOT_RUN_OWNED_PREFIXES
tuple	ALLOWED_CONTEXTS

Detailed Description

Reject unmanaged run-path literals so a layout change cannot leave prose stale.

Function Documentation

tracked_markdown()

list audit_path_literals.tracked_markdown

(

)

Markdown files the current commit carries.

Returns

Sorted Markdown paths.

Definition at line 85 of file audit_path_literals.py.

def tracked_markdown() -> list:
    """!
    @brief Markdown files the current commit carries.
    @return Sorted Markdown paths.
    """
    found = enumerate_repository_files(REPO_ROOT, ".md", frozenset(SKIP_DIRS))
    if found is None:
        return sorted(path for path in REPO_ROOT.rglob("*.md") if path.is_file())
    return found
 
 

Here is the caller graph for this function:

in_code_block()

bool audit_path_literals.in_code_block	(	list	lines,
		int	index
	)

Whether a line sits inside a fenced code block.

Parameters

[in]	lines	All lines of the file.
[in]	index	Zero-based line index.

Returns

True when the line is inside a fence.

Definition at line 96 of file audit_path_literals.py.

def in_code_block(lines: list, index: int) -> bool:
    """!
    @brief Whether a line sits inside a fenced code block.
    @param[in] lines All lines of the file.
    @param[in] index Zero-based line index.
    @return True when the line is inside a fence.
    """
    fences = sum(1 for line in lines[:index] if line.lstrip().startswith("```"))
    return fences % 2 == 1
 
 

Here is the caller graph for this function:

main()

int audit_path_literals.main

(

)

Fail when narrative prose hardcodes a run-relative path.

Returns

Process status code.

Definition at line 107 of file audit_path_literals.py.

def main() -> int:
    """!
    @brief Fail when narrative prose hardcodes a run-relative path.
    @return Process status code.
    """
    contract = json.loads(TOPOLOGY.read_text(encoding="utf-8"))
    identities = [a["id"] for a in contract["artifacts"]]
    violations: list = []
    scanned = 0
    for path in tracked_markdown():
        if str(path.relative_to(REPO_ROOT)) in HISTORICAL:
            continue
        text = path.read_text(encoding="utf-8", errors="replace")
        lines = text.splitlines()
        scanned += 1
        for number, line in enumerate(lines):
            if in_code_block(lines, number) or any(token in line for token in ALLOWED_CONTEXTS):
                continue
            probe = NOT_RUN_OWNED_PREFIXES.sub("", line)
            # `<repo>/logs/...` is the repository's own build and test log directory,
            # which no run configuration moves. Remove the whole reference before
            # looking for bare prefixes, so the distinct notation actually buys the
            # author something rather than leaving a bare `logs/` behind.
            probe = REPO_OWNED.sub("", probe)
            probe = WORKSPACE_OWNED.sub("", probe)
            if MANAGED.search(line):
                found, advice = "unmanaged run-path literal", (
                    "Use logical notation such as `<run.config>`, or move the concrete "
                    "path into a runnable command block.")
            elif PLACEHOLDER_ROOT.search(line):
                found, advice = "run-owned directory named under an unresolved run root", (
                    "`<run_dir>/logs/...` names a subdirectory without naming the "
                    "contract that fixes it. Use the logical identity - "
                    "`<run.runtime_logs>/...` - which artifact_topology.json maps.")
            elif BARE_PREFIX.search(probe):
                match = BARE_PREFIX.search(probe)
                found, advice = f"bare run-owned prefix `{match.group(0)}`", (
                    "A bare `logs/...` or `config/...` does not say which owner is "
                    "meant. Use the run's logical identity - `<run.runtime_logs>/...`, "
                    "`<run.solver_output>/...` - or name the other owner explicitly "
                    "with `<repo>/logs/...` or `<workspace>/config/...`.")
            else:
                continue
            violations.append(
                f"{path.relative_to(REPO_ROOT)}:{number + 1}: {found}\n"
                f"      {line.strip()[:96]}\n"
                f"      {advice}"
            )
    if violations:
        print("Unmanaged run-path literals in narrative prose:", file=sys.stderr)
        for violation in violations:
            print(f"  {violation}", file=sys.stderr)
        print(
            f"\nLogical identities are declared in tests/tooling/artifact_topology.json "
            f"({len(identities)} identities). Narrative pages should refer to those, so a layout "
            f"change is a contract change rather than a prose hunt.",
            file=sys.stderr,
        )
        return 1
    print(f"Path-literal audit passed: {scanned} Markdown files, no unmanaged run-path literals in prose.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

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

Definition at line 16 of file audit_path_literals.py.

TOPOLOGY

str audit_path_literals.TOPOLOGY = REPO_ROOT / "tests" / "tooling" / "artifact_topology.json"

Definition at line 17 of file audit_path_literals.py.

SKIP_DIRS

dict audit_path_literals.SKIP_DIRS = {".git", "docs_build", "obj", "bin", "stubs", "runs", "studies", "__pycache__", ".pytest_cache"}

Definition at line 18 of file audit_path_literals.py.

HISTORICAL

dict audit_path_literals.HISTORICAL = {"docs/CHANGELOG.md"}

Definition at line 21 of file audit_path_literals.py.

RUN_OWNED

str audit_path_literals.RUN_OWNED = "config|logs|output|scheduler|visualization|checkpoints"

Definition at line 31 of file audit_path_literals.py.

MANAGED

audit_path_literals.MANAGED

Initial value:

=  re.compile(
    r"(?<![\w./<])runs/(?:<[^>]+>|\$\{[^}]+\}|[A-Za-z0-9_.*-]+)/(" + RUN_OWNED + r")\b")

Definition at line 34 of file audit_path_literals.py.

PLACEHOLDER_ROOT

audit_path_literals.PLACEHOLDER_ROOT

Initial value:

=  re.compile(
    r"<(?:run_dir|run|RUN_DIR)>/(" + RUN_OWNED + r")\b")

Definition at line 40 of file audit_path_literals.py.

BARE_PREFIX

audit_path_literals.BARE_PREFIX

Initial value:

=  re.compile(
    r"(?<![\w./<>-])(" + RUN_OWNED + r")/(?![A-Za-z0-9_./*-]*[<>])[A-Za-z0-9_./*-]*")

Definition at line 51 of file audit_path_literals.py.

REPO_OWNED

audit_path_literals.REPO_OWNED = re.compile(r"<repo>/[A-Za-z0-9_][A-Za-z0-9_./*<>-]*")

Definition at line 58 of file audit_path_literals.py.

WORKSPACE_OWNED

audit_path_literals.WORKSPACE_OWNED = re.compile(r"<workspace>/[A-Za-z0-9_][A-Za-z0-9_./*<>-]*")

Definition at line 64 of file audit_path_literals.py.

REPO_CONFIG_SUBDIRS

tuple audit_path_literals.REPO_CONFIG_SUBDIRS

Initial value:

=  ("guide.md", "build", "grids", "initial_conditions", "monitors",
                       "postprocessors", "profiles", "runtime", "schedulers", "solvers",
                       "studies")

Definition at line 70 of file audit_path_literals.py.

NOT_RUN_OWNED_PREFIXES

audit_path_literals.NOT_RUN_OWNED_PREFIXES

Initial value:

=  re.compile(
    r"(?<![\w./<>-])config/(?:" + "|".join(
        name.replace(".", r"\.") for name in REPO_CONFIG_SUBDIRS) + r")\b")

Definition at line 73 of file audit_path_literals.py.

ALLOWED_CONTEXTS

tuple audit_path_literals.ALLOWED_CONTEXTS

Initial value:

=  (
    "```",          # runnable command examples
    "@verbinclude", # embedded executable templates
    "@code",
)

Definition at line 78 of file audit_path_literals.py.