Skip to content

File header

file_header

FileHeaderHook — file header extraction for protocol briefings.

Protocol hook that extracts the first ~30 lines of source files referenced by source_body results, providing import blocks, __all__, and TYPE_CHECKING context without requiring a full Read. Registered as ast:file-header via axm.hooks entry point.

FileHeaderHook

Extract the first ~30 lines of source files.

Reads path from params (or working_dir from context) and files from params. When files is not provided, extracts file paths from source_body in context.

Source code in packages/axm-ast/src/axm_ast/hooks/file_header.py
Python
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class FileHeaderHook:
    """Extract the first ~30 lines of source files.

    Reads ``path`` from *params* (or ``working_dir`` from context)
    and ``files`` from *params*.  When *files* is not provided,
    extracts file paths from ``source_body`` in context.
    """

    def execute(self, context: dict[str, object], **params: object) -> HookResult:
        """Execute the hook action.

        Args:
            context: Session context dictionary.
            **params: Optional ``files`` (newline-separated paths or list).
                Optional ``path`` (overrides ``working_dir`` from context).

        Returns:
            HookResult with ``headers`` list in metadata on success.
        """
        working_dir = _resolve_working_dir(params, context)
        if not working_dir.is_dir():
            return HookResult.fail(f"working_dir not a directory: {working_dir}")

        unique_files = _parse_file_list(params, context)
        if unique_files is None:
            return HookResult.ok(headers=[])

        headers = [
            entry
            for file in unique_files
            if (entry := _extract_single_header(working_dir, file)) is not None
        ]
        return HookResult.ok(headers=headers)
execute(context, **params)

Execute the hook action.

Parameters:

Name Type Description Default
context dict[str, object]

Session context dictionary.

 required
**params object

Optional files (newline-separated paths or list). Optional path (overrides working_dir from context).

 {}

Returns:

Type Description
HookResult

HookResult with headers list in metadata on success.
Source code in packages/axm-ast/src/axm_ast/hooks/file_header.py
Python
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def execute(self, context: dict[str, object], **params: object) -> HookResult:
    """Execute the hook action.

    Args:
        context: Session context dictionary.
        **params: Optional ``files`` (newline-separated paths or list).
            Optional ``path`` (overrides ``working_dir`` from context).

    Returns:
        HookResult with ``headers`` list in metadata on success.
    """
    working_dir = _resolve_working_dir(params, context)
    if not working_dir.is_dir():
        return HookResult.fail(f"working_dir not a directory: {working_dir}")

    unique_files = _parse_file_list(params, context)
    if unique_files is None:
        return HookResult.ok(headers=[])

    headers = [
        entry
        for file in unique_files
        if (entry := _extract_single_header(working_dir, file)) is not None
    ]
    return HookResult.ok(headers=headers)