generate_capability_inventory Namespace Reference

Functions
dict	load_registry ()
	Load the capability family registry.
	literal (ast.AST node)
	Evaluate a literal AST node, additionally accepting the bare set() call that appears in the boundary-handler specs for empty parameter sets.
ast.Module	module_syntax (str module)
	Parse a dotted module into one syntax tree, whether file or package.
dict[str, dict]	python_dict_values (str module, str symbol)
	Read a public-surface dictionary from the CLI package without importing PETSc.
dict[str, dict]	python_normalizer_values (str module, str symbol)
	Read the canonical selector strings accepted by a normalizer function.
str	function_body (str path, str function)
	Return the source text of one C function, so extraction never spans the file.
dict	python_membership_values (str module, str symbol)
	Read the accepted values from a normalizer that validates by set membership.
dict	python_equality_chain_values (str module, str symbol)
	Read accepted values from a normalizer that compares against string literals.
dict[str, str]	c_string_map_values (str path, str function)
	Extract the case-insensitive selector strings a C parser accepts.
dict[str, str]	c_token_map_values (str path, str function, str variable, str field)
	Extract an exact-match token chain that assigns an enum to a context field.
set[str]	c_switch_values (str path, str function, str prefix)
	Extract the enum constants a C factory switch dispatches on.
set[str]	c_dispatch_values (str path, str function, str prefix)
	Extract the enum constants an if/else dispatch chain compares against.
set[str]	c_enum_values (str path, str symbol)
	Extract the members of a C enum.
dict	python_constant_values (str module, str symbol)
	Read the accepted values from a named module-level choice set.
dict	collect (dict family)
	Build one family's inventory record from its declared sources.
None	apply_metadata (list[dict] inventory, dict registry)
	Merge declared per-value metadata (status, alias target) into the inventory.
dict[str, int]	classify (list[dict] inventory)
	Count selectable, alias, and latent values separately.
None	apply_reachability (list[dict] inventory, dict registry)
	Mark declared values that no other family can actually satisfy as latent.
str	entry_anchor (dict registry_entry, str value)
	Anchor name of the Tier-2 entry for one selector value.
str	html_escape (str text)
	Escape text for inclusion in generated HTML.
set	documented_entries (dict family, dict registry_entry)
	Values whose Tier-2 entry anchor is actually present on the family page.
str	render_family (dict family, dict registry_entry)
	Render one family's value table as a Doxygen-includable HTML fragment.
Path	family_fragment_path (str family_id)
	Path of the per-family includable fragment.
str	render_evidence_matrix (list[dict] inventory, dict registry)
	Render the project-wide capability-by-evidence matrix as an HTML fragment.
str	render_markdown (list[dict] inventory)
	Render the inventory as a Doxygen-includable Markdown fragment.
int	main ()
	Generate the capability inventory artifacts.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	REGISTRY_PATH = REPO_ROOT / "tests" / "tooling" / "capability_families.json"
str	GENERATED_DIR = REPO_ROOT / "docs" / "generated"

Detailed Description

Extract the public capability inventory from executable sources and render it for the docs.

Function Documentation

load_registry()

dict generate_capability_inventory.load_registry

(

)

Load the capability family registry.

Returns

Parsed registry mapping.

Definition at line 19 of file generate_capability_inventory.py.

def load_registry() -> dict:
    """!
    @brief Load the capability family registry.
    @return Parsed registry mapping.
    """
    return json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
 
 

Here is the caller graph for this function:

literal()

generate_capability_inventory.literal

(

ast.AST

node

)

Evaluate a literal AST node, additionally accepting the bare set() call that appears in the boundary-handler specs for empty parameter sets.

Parameters

[in]

node

Parsed AST node.

Returns

The Python value the node denotes.

Definition at line 27 of file generate_capability_inventory.py.

def literal(node: ast.AST):
    """!
    @brief Evaluate a literal AST node, additionally accepting the bare `set()` call
           that appears in the boundary-handler specs for empty parameter sets.
    @param[in] node Parsed AST node.
    @return The Python value the node denotes.
    """
    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "set":
        return set(literal(node.args[0])) if node.args else set()
    if isinstance(node, ast.Dict):
        return {literal(k): literal(v) for k, v in zip(node.keys, node.values)}
    if isinstance(node, ast.Set):
        return {literal(e) for e in node.elts}
    if isinstance(node, (ast.List, ast.Tuple)):
        return [literal(e) for e in node.elts]
    return ast.literal_eval(node)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

module_syntax()

ast.Module generate_capability_inventory.module_syntax

(

str

module

)

Parse a dotted module into one syntax tree, whether file or package.

A public surface may be a package: picurv_cli.storage exposes its constants through its __init__, but they are defined across its modules. Concatenating their bodies lets the readers below stay written against a single tree, which is what they mean by "the module".

Parameters

[in]

module

Dotted module name.

Returns

Syntax tree covering every file the module resolves to.

Definition at line 45 of file generate_capability_inventory.py.

def module_syntax(module: str) -> ast.Module:
    """!
    @brief Parse a dotted module into one syntax tree, whether file or package.
 
    @details A public surface may be a package: `picurv_cli.storage` exposes its
             constants through its `__init__`, but they are defined across its
             modules. Concatenating their bodies lets the readers below stay written
             against a single tree, which is what they mean by "the module".
    @param[in] module Dotted module name.
    @return Syntax tree covering every file the module resolves to.
    """
    relative = Path(*module.split("."))
    package = REPO_ROOT / relative
    if package.is_dir():
        combined = ast.Module(body=[], type_ignores=[])
        for child in sorted(package.glob("*.py")):
            if child.name == "__init__.py":
                continue
            combined.body.extend(ast.parse(child.read_text(encoding="utf-8")).body)
        return combined
    return ast.parse((REPO_ROOT / relative.with_suffix(".py")).read_text(encoding="utf-8"))
 
 

Here is the caller graph for this function:

python_dict_values()

dict[str, dict] generate_capability_inventory.python_dict_values	(	str	module,
		str	symbol
	)

Read a public-surface dictionary from the CLI package without importing PETSc.

Parameters

[in]	module	Dotted module name.
[in]	symbol	Module-level dictionary name.

Returns

Mapping of selector value to its declared parameter contract.

Definition at line 68 of file generate_capability_inventory.py.

def python_dict_values(module: str, symbol: str) -> dict[str, dict]:
    """!
    @brief Read a public-surface dictionary from the CLI package without importing PETSc.
    @param[in] module Dotted module name.
    @param[in] symbol Module-level dictionary name.
    @return Mapping of selector value to its declared parameter contract.
    """
    tree = module_syntax(module)
    for node in tree.body:
        if not isinstance(node, ast.Assign):
            continue
        targets = [t.id for t in node.targets if isinstance(t, ast.Name)]
        if symbol not in targets:
            continue
        raw = literal(node.value)
        result: dict[str, dict] = {}
        for key, value in raw.items():
            if isinstance(value, dict):
                result[key] = {
                    "types": sorted(value.get("types", [])),
                    "required_params": sorted(value.get("required_params", [])),
                    "optional_params": sorted(value.get("optional_params", [])),
                }
            else:
                result[key] = {"maps_to": value}
        return result
    raise RuntimeError(f"{symbol} not found in {module}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

python_normalizer_values()

dict[str, dict] generate_capability_inventory.python_normalizer_values	(	str	module,
		str	symbol
	)

Read the canonical selector strings accepted by a normalizer function.

Parameters

[in]	module	Dotted module name.
[in]	symbol	Normalizer function name.

Returns

Mapping of canonical value to the runtime token it maps to.

Definition at line 97 of file generate_capability_inventory.py.

def python_normalizer_values(module: str, symbol: str) -> dict[str, dict]:
    """!
    @brief Read the canonical selector strings accepted by a normalizer function.
    @param[in] module Dotted module name.
    @param[in] symbol Normalizer function name.
    @return Mapping of canonical value to the runtime token it maps to.
    """
    tree = module_syntax(module)
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef) and node.name == symbol:
            for inner in ast.walk(node):
                if isinstance(inner, ast.Dict) and inner.keys:
                    try:
                        mapping = ast.literal_eval(inner)
                    except ValueError:
                        continue
                    if all(isinstance(k, str) for k in mapping):
                        return {k: {"maps_to": v} for k, v in mapping.items()}
    raise RuntimeError(f"no canonical mapping found in {module}.{symbol}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

function_body()

str generate_capability_inventory.function_body	(	str	path,
		str	function
	)

Return the source text of one C function, so extraction never spans the file.

Parameters

[in]	path	Repository-relative C source path.
[in]	function	Function name to isolate.

Returns

Source text of that function body.

Exceptions

RuntimeError

when the function cannot be located.

Definition at line 118 of file generate_capability_inventory.py.

def function_body(path: str, function: str) -> str:
    """!
    @brief Return the source text of one C function, so extraction never spans the file.
    @param[in] path Repository-relative C source path.
    @param[in] function Function name to isolate.
    @return Source text of that function body.
    @throws RuntimeError when the function cannot be located.
    """
    text = (REPO_ROOT / path).read_text(encoding="utf-8")
    match = re.search(rf"^[A-Za-z_][\w \*]*\b{re.escape(function)}\s*\‍(", text, re.M)
    if not match:
        raise RuntimeError(f"function {function} not found in {path}")
    index = text.index("{", match.end() - 1)
    depth = 0
    for offset in range(index, len(text)):
        if text[offset] == "{":
            depth += 1
        elif text[offset] == "}":
            depth -= 1
            if depth == 0:
                return text[index : offset + 1]
    raise RuntimeError(f"unbalanced braces while reading {function} in {path}")
 
 

Here is the caller graph for this function:

python_membership_values()

dict generate_capability_inventory.python_membership_values	(	str	module,
		str	symbol
	)

Read the accepted values from a normalizer that validates by set membership.

Some normalizers check if value not in {...} rather than mapping through a dict. The accepted set is still the public surface, so it is extracted the same way rather than being hand-listed.

Parameters

[in]	module	Dotted module name.
[in]	symbol	Normalizer function name.

Returns

Mapping of accepted value to the token it resolves to.

Definition at line 142 of file generate_capability_inventory.py.

def python_membership_values(module: str, symbol: str) -> dict:
    """!
    @brief Read the accepted values from a normalizer that validates by set membership.
 
    @details Some normalizers check `if value not in {...}` rather than mapping through a
             dict. The accepted set is still the public surface, so it is extracted the
             same way rather than being hand-listed.
    @param[in] module Dotted module name.
    @param[in] symbol Normalizer function name.
    @return Mapping of accepted value to the token it resolves to.
    """
    tree = module_syntax(module)
    for node in ast.walk(tree):
        if not (isinstance(node, ast.FunctionDef) and node.name == symbol):
            continue
        collected: dict = {}
        for inner in ast.walk(node):
            if isinstance(inner, ast.Set):
                try:
                    members = {literal(element) for element in inner.elts}
                except (ValueError, TypeError):
                    continue
                if all(isinstance(member, str) for member in members):
                    for member in members:
                        collected.setdefault(member, {"maps_to": member})
        if collected:
            return collected
    raise RuntimeError(f"no membership set found in {module}.{symbol}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

python_equality_chain_values()

dict generate_capability_inventory.python_equality_chain_values	(	str	module,
		str	symbol
	)

Read accepted values from a normalizer that compares against string literals.

A third normalizer shape: if normalized == "ucat": ... elif ... == "ucont". The compared literals are the public surface, so they are extracted rather than hand-listed, keeping the inventory tied to the code.

Parameters

[in]	module	Dotted module name.
[in]	symbol	Normalizer function name.

Returns

Mapping of accepted value to itself.

Definition at line 172 of file generate_capability_inventory.py.

def python_equality_chain_values(module: str, symbol: str) -> dict:
    """!
    @brief Read accepted values from a normalizer that compares against string literals.
 
    @details A third normalizer shape: `if normalized == "ucat": ... elif ... == "ucont"`.
             The compared literals are the public surface, so they are extracted rather
             than hand-listed, keeping the inventory tied to the code.
    @param[in] module Dotted module name.
    @param[in] symbol Normalizer function name.
    @return Mapping of accepted value to itself.
    """
    tree = module_syntax(module)
    for node in ast.walk(tree):
        if not (isinstance(node, ast.FunctionDef) and node.name == symbol):
            continue
        collected: dict = {}
        for inner in ast.walk(node):
            if not isinstance(inner, ast.Compare):
                continue
            if not any(isinstance(op, (ast.Eq, ast.NotEq)) for op in inner.ops):
                continue
            for comparator in inner.comparators:
                if isinstance(comparator, ast.Constant) and isinstance(comparator.value, str):
                    if comparator.value:
                        collected.setdefault(comparator.value, {"maps_to": comparator.value})
        if collected:
            return collected
    raise RuntimeError(f"no equality chain found in {module}.{symbol}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

c_string_map_values()

dict[str, str] generate_capability_inventory.c_string_map_values	(	str	path,
		str	function
	)

Extract the case-insensitive selector strings a C parser accepts.

Parameters

[in]	path	Repository-relative C source path.
[in]	function	Parser function name.

Returns

Mapping of accepted selector string to the enum constant it selects.

Definition at line 202 of file generate_capability_inventory.py.

def c_string_map_values(path: str, function: str) -> dict[str, str]:
    """!
    @brief Extract the case-insensitive selector strings a C parser accepts.
    @param[in] path Repository-relative C source path.
    @param[in] function Parser function name.
    @return Mapping of accepted selector string to the enum constant it selects.
    """
    body = function_body(path, function)
    pairs = re.findall(
        r'strcasecmp\‍(\s*str\s*,\s*"([^"]+)"\s*\‍)\s*==\s*0\s*\‍)\s*\*handler_out\s*=\s*([A-Z][A-Z0-9_]+)',
        body,
    )
    return dict(pairs)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

c_token_map_values()

dict[str, str] generate_capability_inventory.c_token_map_values	(	str	path,
		str	function,
		str	variable,
		str	field
	)

Extract an exact-match token chain that assigns an enum to a context field.

Handles the strcmp(buf, "TOKEN") == 0 ... field = ENUM; shape used for generated PETSc option tokens, including chains where several tokens share one assignment (an alias arm).

Parameters

[in]	path	Repository-relative C source path.
[in]	function	Enclosing function name.
[in]	variable	Name of the char buffer holding the option value.
[in]	field	Assigned context field, for example mom_solver_type.

Returns

Mapping of accepted token to the enum constant it selects.

Definition at line 217 of file generate_capability_inventory.py.

def c_token_map_values(path: str, function: str, variable: str, field: str) -> dict[str, str]:
    """!
    @brief Extract an exact-match token chain that assigns an enum to a context field.
 
    Handles the `strcmp(buf, "TOKEN") == 0 ... field = ENUM;` shape used for
    generated PETSc option tokens, including chains where several tokens share one
    assignment (an alias arm).
    @param[in] path Repository-relative C source path.
    @param[in] function Enclosing function name.
    @param[in] variable Name of the char buffer holding the option value.
    @param[in] field Assigned context field, for example `mom_solver_type`.
    @return Mapping of accepted token to the enum constant it selects.
    """
    body = function_body(path, function)
    mapping: dict[str, str] = {}
    pattern = re.compile(
        r'((?:strcmp\‍(\s*' + re.escape(variable) + r'\s*,\s*"[^"]+"\s*\‍)\s*==\s*0\s*\|?\|?\s*)+)'
        r"[^{]*\{[^}]*?\b" + re.escape(field) + r"\s*=\s*([A-Z][A-Z0-9_]+)\s*;",
        re.S,
    )
    for arm, enum in pattern.findall(body):
        for token in re.findall(r'"([^"]+)"', arm):
            mapping[token] = enum
    return mapping
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

c_switch_values()

set[str] generate_capability_inventory.c_switch_values	(	str	path,
		str	function,
		str	prefix
	)

Extract the enum constants a C factory switch dispatches on.

Parameters

[in]	path	Repository-relative C source path.
[in]	function	Enclosing function name.
[in]	prefix	Enum constant prefix.

Returns

Set of dispatched enum constants.

Definition at line 243 of file generate_capability_inventory.py.

def c_switch_values(path: str, function: str, prefix: str) -> set[str]:
    """!
    @brief Extract the enum constants a C factory switch dispatches on.
    @param[in] path Repository-relative C source path.
    @param[in] function Enclosing function name.
    @param[in] prefix Enum constant prefix.
    @return Set of dispatched enum constants.
    """
    body = function_body(path, function)
    return set(re.findall(rf"case\s+({re.escape(prefix)}[A-Z0-9_]+)\s*:", body))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

c_dispatch_values()

set[str] generate_capability_inventory.c_dispatch_values	(	str	path,
		str	function,
		str	prefix
	)

Extract the enum constants an if/else dispatch chain compares against.

Parameters

[in]	path	Repository-relative C source path.
[in]	function	Enclosing function name.
[in]	prefix	Enum constant prefix.

Returns

Set of enum constants the dispatch acts on.

Definition at line 255 of file generate_capability_inventory.py.

def c_dispatch_values(path: str, function: str, prefix: str) -> set[str]:
    """!
    @brief Extract the enum constants an if/else dispatch chain compares against.
    @param[in] path Repository-relative C source path.
    @param[in] function Enclosing function name.
    @param[in] prefix Enum constant prefix.
    @return Set of enum constants the dispatch acts on.
    """
    body = function_body(path, function)
    return set(re.findall(rf"==\s*({re.escape(prefix)}[A-Z0-9_]+)", body))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

c_enum_values()

set[str] generate_capability_inventory.c_enum_values	(	str	path,
		str	symbol
	)

Extract the members of a C enum.

Parameters

[in]	path	Repository-relative header path.
[in]	symbol	Enum type name.

Returns

Set of enum member names.

Definition at line 267 of file generate_capability_inventory.py.

def c_enum_values(path: str, symbol: str) -> set[str]:
    """!
    @brief Extract the members of a C enum.
    @param[in] path Repository-relative header path.
    @param[in] symbol Enum type name.
    @return Set of enum member names.
    """
    text = (REPO_ROOT / path).read_text(encoding="utf-8")
    match = re.search(r"typedef\s+enum\s*\{([^{}]*)\}\s*" + re.escape(symbol) + r"\s*;", text, re.S)
    if not match:
        raise RuntimeError(f"enum {symbol} not found in {path}")
    # Split on commas rather than requiring one member per line: a single-line enum
    # would otherwise be silently under-extracted, which is the failure class these
    # extractors exist to eliminate.
    members = set()
    body = re.sub(r"/\*.*?\*/", "", match.group(1), flags=re.S)
    body = re.sub(r"//[^\n]*", "", body)
    for chunk in body.split(","):
        name = re.match(r"\s*([A-Z][A-Z0-9_]*)\s*(?:=|$)", chunk)
        if name:
            members.add(name.group(1))
    return members
 
 

Here is the caller graph for this function:

python_constant_values()

dict generate_capability_inventory.python_constant_values	(	str	module,
		str	symbol
	)

Read the accepted values from a named module-level choice set.

The preferred shape. A choice set written as an inline literal at its point of use is invisible to the census, so the rule is that it must be a named module-level constant - a tuple, list, set, or dict of strings. A dict maps each accepted spelling to what it resolves to; a sequence maps each value to itself.

Parameters

[in]	module	Dotted module name.
[in]	symbol	Constant name.

Returns

Mapping of accepted value to the token it resolves to.

Definition at line 291 of file generate_capability_inventory.py.

def python_constant_values(module: str, symbol: str) -> dict:
    """!
    @brief Read the accepted values from a named module-level choice set.
 
    @details The preferred shape. A choice set written as an inline literal at its point
             of use is invisible to the census, so the rule is that it must be a named
             module-level constant - a tuple, list, set, or dict of strings. A dict maps
             each accepted spelling to what it resolves to; a sequence maps each value
             to itself.
    @param[in] module Dotted module name.
    @param[in] symbol Constant name.
    @return Mapping of accepted value to the token it resolves to.
    """
    tree = module_syntax(module)
    for node in tree.body:
        if not isinstance(node, ast.Assign):
            continue
        if not any(isinstance(target, ast.Name) and target.id == symbol
                   for target in node.targets):
            continue
        value = literal(node.value)
        if isinstance(value, dict):
            if not all(isinstance(k, str) for k in value):
                raise RuntimeError(f"{module}.{symbol} is not keyed by strings")
            # A dict of strings declares spellings and what each resolves to. A dict
            # whose values are anything else - a per-value specification, say - declares
            # the keys as the choice set and carries its own detail alongside.
            if all(isinstance(v, str) for v in value.values()):
                return {k: {"maps_to": v} for k, v in value.items()}
            return {k: {"maps_to": k} for k in value}
        if isinstance(value, (tuple, list, set, frozenset)):
            members = list(value)
            if not all(isinstance(member, str) for member in members):
                raise RuntimeError(f"{module}.{symbol} is not a sequence of strings")
            return {member: {"maps_to": member} for member in members}
        raise RuntimeError(f"{module}.{symbol} is not a choice set")
    raise RuntimeError(f"no module-level constant {symbol} in {module}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

collect()

dict generate_capability_inventory.collect

(

dict

family

)

Build one family's inventory record from its declared sources.

Parameters

[in]

family

Family registry entry.

Returns

Inventory record for the family.

Definition at line 330 of file generate_capability_inventory.py.

def collect(family: dict) -> dict:
    """!
    @brief Build one family's inventory record from its declared sources.
    @param[in] family Family registry entry.
    @return Inventory record for the family.
    """
    surface = family["public_surface"]
    if surface["kind"] == "python_dict":
        values = python_dict_values(surface["module"], surface["symbol"])
    elif surface["kind"] == "python_normalizer":
        values = python_normalizer_values(surface["module"], surface["symbol"])
    elif surface["kind"] == "python_membership":
        values = python_membership_values(surface["module"], surface["symbol"])
    elif surface["kind"] == "python_equality_chain":
        values = python_equality_chain_values(surface["module"], surface["symbol"])
    elif surface["kind"] == "python_constant":
        values = python_constant_values(surface["module"], surface["symbol"])
    else:
        raise RuntimeError(f"unknown public_surface kind: {surface['kind']}")
 
    parity = []
    for source in family.get("parity_sources", []):
        kind = source["kind"]
        if kind == "c_string_map":
            found = c_string_map_values(source["path"], source["function"])
        elif kind == "c_token_map":
            found = c_token_map_values(
                source["path"], source["function"], source["variable"], source["field"]
            )
        elif kind == "c_switch":
            found = c_switch_values(source["path"], source["function"], source["prefix"])
        elif kind == "c_dispatch":
            found = c_dispatch_values(source["path"], source["function"], source["prefix"])
        elif kind == "c_enum":
            found = c_enum_values(source["path"], source["symbol"])
        else:
            raise RuntimeError(f"unknown parity source kind: {kind}")
        if isinstance(found, dict):
            parity.append({"source": source, "values": sorted(found), "mapping": found})
        else:
            parity.append({"source": source, "values": sorted(found)})
 
    return {
        "id": family["id"],
        "title": family["title"],
        "selector": family["selector"],
        "family_page": family["family_page"],
        "public_values": values,
        "parity": parity,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

apply_metadata()

None generate_capability_inventory.apply_metadata	(	list[dict]	inventory,
		dict	registry
	)

Merge declared per-value metadata (status, alias target) into the inventory.

Parameters

[in,out]	inventory	Collected family records.
[in]	registry	Parsed registry mapping.

Returns

None.

Definition at line 382 of file generate_capability_inventory.py.

def apply_metadata(inventory: list[dict], registry: dict) -> None:
    """!
    @brief Merge declared per-value metadata (status, alias target) into the inventory.
    @param[in,out] inventory Collected family records.
    @param[in] registry Parsed registry mapping.
    @return None.
    """
    entries = {entry["id"]: entry for entry in registry["families"]}
    for family in inventory:
        declared = entries[family["id"]].get("value_metadata", {})
        for name, spec in family["public_values"].items():
            meta = declared.get(name, {})
            if meta.get("alias_of"):
                spec["alias_of"] = meta["alias_of"]
            if meta.get("spelling_of"):
                spec["spelling_of"] = meta["spelling_of"]
            # A spelling has no status of its own: it inherits the canonical value's,
            # so a defective capability cannot look supported under another name. A
            # deprecated alias keeps its own status - being retired is a fact about the
            # alias, not about what it resolves to.
            spelling_target = meta.get("spelling_of")
            if spelling_target:
                spec["status"] = declared.get(spelling_target, {}).get("status", "supported")
            elif meta.get("status"):
                spec["status"] = meta["status"]
 
 

Here is the caller graph for this function:

classify()

dict[str, int] generate_capability_inventory.classify

(

list[dict]

inventory

)

Count selectable, alias, and latent values separately.

A single total conflates three different things: what a user can choose, what is only kept readable for old configs, and what is declared but unreachable.

Parameters

[in]

inventory

Collected family records.

Returns

Mapping of category to count.

Definition at line 409 of file generate_capability_inventory.py.

def classify(inventory: list[dict]) -> dict[str, int]:
    """!
    @brief Count selectable, alias, and latent values separately.
 
    A single total conflates three different things: what a user can choose, what is
    only kept readable for old configs, and what is declared but unreachable.
    @param[in] inventory Collected family records.
    @return Mapping of category to count.
    """
    counts = {"selectable": 0, "spelling": 0, "alias": 0, "latent": 0}
    for family in inventory:
        for spec in family["public_values"].values():
            if spec.get("reachability") == "latent":
                counts["latent"] += 1
            elif spec.get("alias_of"):
                counts["alias"] += 1
            elif spec.get("spelling_of"):
                counts["spelling"] += 1
            else:
                counts["selectable"] += 1
    return counts
 
 

Here is the caller graph for this function:

apply_reachability()

None generate_capability_inventory.apply_reachability	(	list[dict]	inventory,
		dict	registry
	)

Mark declared values that no other family can actually satisfy as latent.

A boundary type is only selectable if some public handler accepts it. Listing a type no handler supports advertises a capability every complete configuration would be rejected for.

Parameters

[in,out]	inventory	Collected family records.
[in]	registry	Parsed registry mapping.

Returns

None.

Definition at line 432 of file generate_capability_inventory.py.

def apply_reachability(inventory: list[dict], registry: dict) -> None:
    """!
    @brief Mark declared values that no other family can actually satisfy as latent.
 
    A boundary type is only selectable if some public handler accepts it. Listing a
    type no handler supports advertises a capability every complete configuration
    would be rejected for.
    @param[in,out] inventory Collected family records.
    @param[in] registry Parsed registry mapping.
    @return None.
    """
    by_id = {family["id"]: family for family in inventory}
    for entry in registry["families"]:
        spec = entry.get("reachable_from")
        if not spec:
            continue
        provider = by_id.get(spec["family"])
        target = by_id.get(entry["id"])
        if provider is None or target is None:
            raise RuntimeError(f"reachable_from names an unknown family: {spec['family']}")
        reachable: set[str] = set()
        for value in provider["public_values"].values():
            reachable.update(value.get(spec["field"], []))
        for name, value in target["public_values"].items():
            resolved = value.get("maps_to", name)
            # Reachability is an independent axis. Overwriting `status` here destroyed
            # the declared lifecycle, which silently disabled lifecycle enforcement for
            # every family using reachable_from.
            is_reachable = resolved in reachable
            value["reachable"] = is_reachable
            value["reachability"] = "reachable" if is_reachable else "latent"
 
 

Here is the caller graph for this function:

entry_anchor()

str generate_capability_inventory.entry_anchor	(	dict	registry_entry,
		str	value
	)

Anchor name of the Tier-2 entry for one selector value.

Parameters

[in]	registry_entry	Registry entry carrying the anchor prefix.
[in]	value	Public selector value.

Returns

Anchor name.

Definition at line 465 of file generate_capability_inventory.py.

def entry_anchor(registry_entry: dict, value: str) -> str:
    """!
    @brief Anchor name of the Tier-2 entry for one selector value.
    @param[in] registry_entry Registry entry carrying the anchor prefix.
    @param[in] value Public selector value.
    @return Anchor name.
    """
    return registry_entry["entry_anchor_prefix"] + re.sub(r"[^a-z0-9]+", "_", value.lower()).strip("_")
 
 

Here is the caller graph for this function:

html_escape()

str generate_capability_inventory.html_escape

(

str

text

)

Escape text for inclusion in generated HTML.

Parameters

[in]

text

Raw text.

Returns

Escaped text.

Definition at line 475 of file generate_capability_inventory.py.

def html_escape(text: str) -> str:
    """!
    @brief Escape text for inclusion in generated HTML.
    @param[in] text Raw text.
    @return Escaped text.
    """
    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
 
 

Here is the caller graph for this function:

documented_entries()

set generate_capability_inventory.documented_entries	(	dict	family,
		dict	registry_entry
	)

Values whose Tier-2 entry anchor is actually present on the family page.

Generated tables must not link to an entry that does not exist: a deferred or latent value has no anchor, and a dead in-page link is worse than plain text.

Parameters

[in]	family	Collected family record.
[in]	registry_entry	Registry entry naming the family page.

Returns

Set of value names that have an entry.

Definition at line 484 of file generate_capability_inventory.py.

def documented_entries(family: dict, registry_entry: dict) -> set:
    """!
    @brief Values whose Tier-2 entry anchor is actually present on the family page.
 
    Generated tables must not link to an entry that does not exist: a deferred or
    latent value has no anchor, and a dead in-page link is worse than plain text.
    @param[in] family Collected family record.
    @param[in] registry_entry Registry entry naming the family page.
    @return Set of value names that have an entry.
    """
    page = REPO_ROOT / "docs" / "pages" / f"{registry_entry['family_page']}.md"
    if not page.is_file():
        return set()
    text = page.read_text(encoding="utf-8")
    anchors = set(re.findall(r"^@anchor\s+([A-Za-z0-9_]+)\s*$", text, re.M))
    return {
        name
        for name in family["public_values"]
        if entry_anchor(registry_entry, name) in anchors
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

render_family()

str generate_capability_inventory.render_family	(	dict	family,
		dict	registry_entry
	)

Render one family's value table as a Doxygen-includable HTML fragment.

HTML rather than Markdown because Doxygen's plain include command inserts Markdown verbatim as a code block, while its HTML include command inserts real markup. Each value links to its Tier-2 entry so the inventory is a route into the documentation, not a dead list.

Parameters

[in]	family	Collected family record.
[in]	registry_entry	Registry entry for the same family.

Returns

HTML fragment text.

Definition at line 506 of file generate_capability_inventory.py.

def render_family(family: dict, registry_entry: dict) -> str:
    """!
    @brief Render one family's value table as a Doxygen-includable HTML fragment.
 
    HTML rather than Markdown because Doxygen's plain include command inserts Markdown
    verbatim as a code block, while its HTML include command inserts real markup. Each value links to its
    Tier-2 entry so the inventory is a route into the documentation, not a dead list.
    @param[in] family Collected family record.
    @param[in] registry_entry Registry entry for the same family.
    @return HTML fragment text.
    """
    values = family["public_values"]
    documented_values = documented_entries(family, registry_entry)
    has_params = any("required_params" in v for v in values.values())
    latent_present = any(
        v.get("reachability") == "latent"
        or v.get("alias_of")
        or v.get("spelling_of")
        or v.get("status", "supported") != "supported"
        for v in values.values()
    )
 
    out = [
        f"<!-- GENERATED FILE - do not edit by hand. Family: {family['id']}.",
        "     Regenerate with: make docs-inventory -->",
        '<table class="markdownTable">',
        "<tr>",
    ]
    headers = ["Value", "Applies to", "Required parameters", "Optional parameters"] if has_params \
        else ["Value", "Maps to"]
    if latent_present:
        headers.append("Status")
    out += [f'<th class="markdownTableHeadNone">{h}</th>' for h in headers]
    out.append("</tr>")
 
    for name, spec in sorted(values.items()):
        cells = []
        label = f"<code>{html_escape(name)}</code>"
        # A spelling has no entry of its own: link it to the canonical value's entry.
        # A value whose entry is absent (latent, or deliberately deferred) must not
        # link at all rather than link into nothing.
        target = spec.get("spelling_of") or name
        documented = target in documented_values
        if documented and spec.get("reachability") != "latent":
            label = f'<a href="#{entry_anchor(registry_entry, target)}">{label}</a>'
        cells.append(label)
        if has_params:
            cells.append(", ".join(f"<code>{html_escape(x)}</code>" for x in spec.get("types", [])) or "-")
            cells.append(
                ", ".join(f"<code>{html_escape(x)}</code>" for x in spec.get("required_params", [])) or "none"
            )
            cells.append(
                ", ".join(f"<code>{html_escape(x)}</code>" for x in spec.get("optional_params", [])) or "none"
            )
        else:
            cells.append(f"<code>{html_escape(str(spec.get('maps_to', '-')))}</code>")
        if latent_present:
            if spec.get("reachability") == "latent":
                cells.append("<b>latent - not selectable</b>")
            elif spec.get("alias_of"):
                cells.append(
                    "<b>deprecated</b> - alias of <code>"
                    + html_escape(str(spec["alias_of"]))
                    + "</code>"
                )
            elif spec.get("spelling_of"):
                cells.append(
                    "accepted spelling of <code>"
                    + html_escape(str(spec["spelling_of"]))
                    + "</code>"
                )
            else:
                # Show the lifecycle status, not merely that the value can be typed. A
                # known-defective capability reading "selectable" is the failure this
                # column exists to prevent.
                status = spec.get("status", "supported")
                cells.append(
                    f"<b>{html_escape(status)}</b>" if status != "supported" else "supported"
                )
        out.append("<tr>" + "".join(f'<td class="markdownTableBodyNone">{c}</td>' for c in cells) + "</tr>")
 
    out.append("</table>")
    return "\n".join(out) + "\n"
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

family_fragment_path()

Path generate_capability_inventory.family_fragment_path

(

str

family_id

)

Path of the per-family includable fragment.

Parameters

[in]

family_id

Family identifier.

Returns

Fragment path under the generated directory.

Definition at line 591 of file generate_capability_inventory.py.

def family_fragment_path(family_id: str) -> Path:
    """!
    @brief Path of the per-family includable fragment.
    @param[in] family_id Family identifier.
    @return Fragment path under the generated directory.
    """
    return GENERATED_DIR / f"capability_inventory_{family_id.replace('.', '_')}.html"
 
 

Here is the caller graph for this function:

render_evidence_matrix()

str generate_capability_inventory.render_evidence_matrix	(	list[dict]	inventory,
		dict	registry
	)

Render the project-wide capability-by-evidence matrix as an HTML fragment.

A scientist deciding whether a result is credible needs to see, in one place, what confidence the project claims for each capability. An empty row is a real answer - it says "implemented only".

Parameters

[in]	inventory	Collected family records.
[in]	registry	Parsed registry mapping.

Returns

HTML fragment text.

Definition at line 600 of file generate_capability_inventory.py.

def render_evidence_matrix(inventory: list[dict], registry: dict) -> str:
    """!
    @brief Render the project-wide capability-by-evidence matrix as an HTML fragment.
 
    A scientist deciding whether a result is credible needs to see, in one place,
    what confidence the project claims for each capability. An empty row is a real
    answer - it says "implemented only".
    @param[in] inventory Collected family records.
    @param[in] registry Parsed registry mapping.
    @return HTML fragment text.
    """
    facets = registry["evidence_facets"]
    order = ["unit", "integration", "analytical", "benchmark", "reference", "production"]
    entries = {e["id"]: e for e in registry["families"]}
    out = [
        "<!-- GENERATED FILE - do not edit by hand. Regenerate with: make docs-inventory -->",
        '<table class="markdownTable">',
        "<tr>",
        '<th class="markdownTableHeadNone">Capability</th>',
        '<th class="markdownTableHeadNone">Family</th>',
    ]
    out += [f'<th class="markdownTableHeadNone">{html_escape(facets[f])}</th>' for f in order]
    out.append("</tr>")
    for family in inventory:
        meta = entries[family["id"]].get("value_metadata", {})
        for name, spec in sorted(family["public_values"].items()):
            if spec.get("spelling_of") or spec.get("reachability") == "latent":
                continue
            have = dict(meta.get(name, {}).get("evidence", {}) or {})
            label = f"<code>{html_escape(name)}</code>"
            if name in documented_entries(family, entries[family["id"]]):
                anchor = entry_anchor(entries[family["id"]], name)
                label = f'<a href="{family["family_page"]}.html#{anchor}">{label}</a>'
            cells = [label, f"<code>{html_escape(family['id'])}</code>"]
            cells += [
                (
                    '<span title="'
                    + html_escape("; ".join(have[f]))
                    + '">&#10003;</span>'
                )
                if f in have
                else "&#8212;"
                for f in order
            ]
            out.append("<tr>" + "".join(f'<td class="markdownTableBodyNone">{c}</td>' for c in cells) + "</tr>")
    out.append("</table>")
    return "\n".join(out) + "\n"
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

render_markdown()

str generate_capability_inventory.render_markdown

(

list[dict]

inventory

)

Render the inventory as a Doxygen-includable Markdown fragment.

Parameters

[in]

inventory

Collected family records.

Returns

Markdown text.

Definition at line 649 of file generate_capability_inventory.py.

def render_markdown(inventory: list[dict]) -> str:
    """!
    @brief Render the inventory as a Doxygen-includable Markdown fragment.
    @param[in] inventory Collected family records.
    @return Markdown text.
    """
    lines = [
        "<!-- GENERATED FILE - do not edit by hand.",
        "     Regenerate with: make docs-inventory",
        "     Source of truth: the Python validation layer named per family below. -->",
        "",
    ]
    for family in inventory:
        lines.append(f"### {family['title']}")
        lines.append("")
        lines.append(f"Selector: `{family['selector']}`")
        lines.append("")
        has_params = any("required_params" in v for v in family["public_values"].values())
        if has_params:
            lines.append("| Value | Applies to | Required parameters | Optional parameters |")
            lines.append("|---|---|---|---|")
            for name, spec in sorted(family["public_values"].items()):
                types = ", ".join(f"`{t}`" for t in spec.get("types", [])) or "-"
                req = ", ".join(f"`{p}`" for p in spec.get("required_params", [])) or "none"
                opt = ", ".join(f"`{p}`" for p in spec.get("optional_params", [])) or "none"
                lines.append(f"| `{name}` | {types} | {req} | {opt} |")
        else:
            lines.append("| Value | Maps to |")
            lines.append("|---|---|")
            for name, spec in sorted(family["public_values"].items()):
                lines.append(f"| `{name}` | `{spec.get('maps_to', '-')}` |")
        lines.append("")
    return "\n".join(lines)
 
 

Here is the caller graph for this function:

main()

int generate_capability_inventory.main

(

)

Generate the capability inventory artifacts.

Returns

Process status code.

Definition at line 684 of file generate_capability_inventory.py.

def main() -> int:
    """!
    @brief Generate the capability inventory artifacts.
    @return Process status code.
    """
    parser = argparse.ArgumentParser(description="Generate the public capability inventory.")
    parser.add_argument("--check", action="store_true", help="Fail if generated output is stale.")
    args = parser.parse_args()
 
    registry = load_registry()
    entries = {f["id"]: f for f in registry["families"]}
    inventory = [collect(family) for family in registry["families"]]
    apply_metadata(inventory, registry)
    apply_reachability(inventory, registry)
    snapshot = json.dumps(inventory, indent=2, sort_keys=True) + "\n"
    markdown = render_markdown(inventory)
 
    GENERATED_DIR.mkdir(parents=True, exist_ok=True)
    json_path = GENERATED_DIR / "capability_inventory.json"
    md_path = GENERATED_DIR / "capability_inventory.md"
 
    managed = {json_path: snapshot, md_path: markdown}
    managed[GENERATED_DIR / "evidence_matrix.html"] = render_evidence_matrix(inventory, registry)
    for family in inventory:
        managed[family_fragment_path(family["id"])] = render_family(family, entries[family["id"]])
 
    # Orphan detection is scoped to the files THIS generator owns. Other generators
    # write into the same directory; claiming their output would report false orphans.
    owned_prefixes = ("capability_inventory", "evidence_matrix")
    existing = {
        path
        for path in GENERATED_DIR.iterdir()
        if path.is_file() and path.name.startswith(owned_prefixes)
    }
    orphans = sorted(existing - set(managed))
 
    if args.check:
        problems = [
            f"stale: {path.relative_to(REPO_ROOT)}"
            for path, content in managed.items()
            if not path.is_file() or path.read_text(encoding="utf-8") != content
        ]
        problems += [f"orphan: {path.relative_to(REPO_ROOT)} (no family produces it)" for path in orphans]
        if problems:
            print("Generated capability inventory is out of date:", file=sys.stderr)
            for problem in problems:
                print(f"  {problem}", file=sys.stderr)
            print("\nRegenerate with: make docs-inventory", file=sys.stderr)
            return 1
        print(f"Capability inventory is current ({len(inventory)} families, {len(managed)} managed files).")
        return 0
 
    for path, content in managed.items():
        path.write_text(content, encoding="utf-8")
    for path in orphans:
        path.unlink()
        print(f"Removed orphaned generated file: {path.relative_to(REPO_ROOT)}")
    counts = classify(inventory)
    print(
        f"Wrote capability inventory: {len(inventory)} families, "
        f"{counts['selectable']} canonical, {counts['spelling']} accepted spelling, "
        f"{counts['alias']} deprecated alias, {counts['latent']} latent; "
        f"{len(managed)} managed files."
    )
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

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

Definition at line 14 of file generate_capability_inventory.py.

REGISTRY_PATH

str generate_capability_inventory.REGISTRY_PATH = REPO_ROOT / "tests" / "tooling" / "capability_families.json"

Definition at line 15 of file generate_capability_inventory.py.

GENERATED_DIR

str generate_capability_inventory.GENERATED_DIR = REPO_ROOT / "docs" / "generated"

Definition at line 16 of file generate_capability_inventory.py.