File header

file_header

AstFileHeaderTool — extract the first lines of source files.

Returns the import block, __all__ and TYPE_CHECKING context of one or more files without a full read — the tool form of the legacy ast:file-header hook. Registered as ast_file_header via axm.tools entry point.

AstFileHeaderTool

Bases: AXMTool

Extract the first max_lines lines of one or more source files.

Registered as ast_file_header via axm.tools entry point.

Source code in packages/axm-ast/src/axm_ast/tools/file_header.py

class AstFileHeaderTool(AXMTool):
    """Extract the first ``max_lines`` lines of one or more source files.

    Registered as ``ast_file_header`` via axm.tools entry point.
    """

    domain = "ast"
    tags = frozenset({"header", "imports", "source"})

    @property
    def name(self) -> str:
        """Tool name used for MCP registration."""
        return "ast_file_header"

    def execute(  # type: ignore[override]
        self,
        *,
        files: list[str],
        path: str = ".",
        max_lines: int = _DEFAULT_MAX_LINES,
        **kwargs: object,
    ) -> ToolResult:
        """Extract the header of each file in *files*.

        Args:
            files: File paths relative to *path* (required).
            path: Project root directory (default ``.``).
            max_lines: Number of leading lines to keep per file (default 30).

        Returns:
            ToolResult with a ``headers`` list of ``{file, header}`` entries.
            Files that are missing or binary are skipped.
        """
        working_dir = Path(path).resolve()
        if not working_dir.is_dir():
            error = f"path not a directory: {working_dir}"
            return ToolResult(
                success=False, error=error, text=render_failure_text(error=error)
            )

        unique_files = list(dict.fromkeys(files))
        headers = [
            entry
            for file in unique_files
            if (entry := _extract_header(working_dir, file, max_lines)) is not None
        ]
        data: dict[str, object] = {"headers": headers}
        return ToolResult(success=True, data=data, text=render_text(headers))

name property

Tool name used for MCP registration.

execute(*, files, path='.', max_lines=_DEFAULT_MAX_LINES, **kwargs)

Extract the header of each file in files.

Parameters:

Name	Type	Description	Default
files	list[str]	File paths relative to path (required).	required
path	str	Project root directory (default .).	'.'
max_lines	int	Number of leading lines to keep per file (default 30).	_DEFAULT_MAX_LINES

Returns:

Type	Description
ToolResult	ToolResult with a headers list of {file, header} entries.
ToolResult	Files that are missing or binary are skipped.

Source code in packages/axm-ast/src/axm_ast/tools/file_header.py

def execute(  # type: ignore[override]
    self,
    *,
    files: list[str],
    path: str = ".",
    max_lines: int = _DEFAULT_MAX_LINES,
    **kwargs: object,
) -> ToolResult:
    """Extract the header of each file in *files*.

    Args:
        files: File paths relative to *path* (required).
        path: Project root directory (default ``.``).
        max_lines: Number of leading lines to keep per file (default 30).

    Returns:
        ToolResult with a ``headers`` list of ``{file, header}`` entries.
        Files that are missing or binary are skipped.
    """
    working_dir = Path(path).resolve()
    if not working_dir.is_dir():
        error = f"path not a directory: {working_dir}"
        return ToolResult(
            success=False, error=error, text=render_failure_text(error=error)
        )

    unique_files = list(dict.fromkeys(files))
    headers = [
        entry
        for file in unique_files
        if (entry := _extract_header(working_dir, file, max_lines)) is not None
    ]
    data: dict[str, object] = {"headers": headers}
    return ToolResult(success=True, data=data, text=render_text(headers))