animedex.policy.lint

Docstring lint for backend commands and MCP tools.

The lint enforces plans/02 §4 on a Click command tree: every @cli.command(...) / @mcp.tool(...) callable must have a docstring containing:

• a Backend: line that names the upstream;

• a Rate limit: line stating the documented cap;

• a block delimited by --- LLM Agent Guidance --- and --- End --- for the agent’s policy text.

The helpers below operate on Click command objects so the lint can also drive the auto-extracted Agents Reference page in the docs build (plans/02 §4 and the animedex --agent-guide aggregator).

check_command_docstring

animedex.policy.lint.check_command_docstring(command: Command) → List[str]

Validate one Click command’s docstring against the policy template.

Parameters:

command (click.Command) – A Click click.Command (the decorated callable, not a group).

Returns:

List of human-readable problem descriptions; empty when the docstring is well-formed.

Return type:

list of str

lint_group

animedex.policy.lint.lint_group(group: Group) → List[Dict[str, Any]]

Walk a Click group recursively and collect every problem.

Parameters:

group (click.Group) – A Click click.Group (e.g. the top-level animedex group).

Returns:

List of {"command": "<name path>", "problems": [...]} dicts. Empty when every nested command is well-formed.

Return type:

list of dict

extract_agent_guidance

animedex.policy.lint.extract_agent_guidance(command: Command) → str | None

Extract the --- LLM Agent Guidance --- block.

Returns None when the block is absent (the command never declared one). Raises ApiError with reason="malformed-guidance" when the begin marker is present but the end marker is missing - silent skip would let a typo’d docstring quietly disappear from the --agent-guide listing, which does not run check_command_docstring() first.

Parameters:

command (click.Command) – A Click click.Command.

Returns:

Text between the begin and end delimiters, stripped, or None when the block is absent.

Return type:

str or None

Raises:

ApiError – When the begin marker is present without a matching end marker (reason="malformed-guidance").

collect_agent_guidance

animedex.policy.lint.collect_agent_guidance(group: Group) → List[Dict[str, str]]

Walk a Click group and return every command’s guidance block.

Parameters:

group (click.Group) – A Click click.Group.

Returns:

List of {"command": "<name path>", "guidance": "..."} dicts, in tree-walk order, for every command that has a guidance block.

Return type:

list of dict

selftest

animedex.policy.lint.selftest() → bool

Smoke-test the lint helpers.

Builds a synthetic Click command with the well-formed shape and confirms check_command_docstring returns no problems and extract_agent_guidance returns the block.

Returns:

True on success.

Return type:

bool

main

animedex.policy.lint.main(argv: List[str] | None = None) → int

Console-script entry point for python -m animedex.policy.lint.

Iterates over the registered animedex Click group and exits non-zero when any command violates the policy template.

Parameters:

argv (list of str or None) – Argument list; currently unused (lint scope is always the entire registered group).

Returns:

Process exit code (0 on success, 1 on policy violation).

Return type:

int