skrypt-ai 0.3.3 → 0.4.0

package/dist/template/src/app/docs/scanner/python_parser.md

@@ -0,0 +1,1056 @@
+# Python parser
+
+## Functions
+
+### `get_docstring`
+
+```python
+def get_docstring(node: ast.AST) -> str | None
+```
+
+Use this to extract the docstring from any Python AST node (functions, classes, modules) when parsing or analyzing Python source code programmatically.
+
+Returns the docstring as a `str` if one is present, or `None` if the node has no docstring.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| node | `ast.AST` | ✅ | Any parsed AST node — typically a `Module`, `FunctionDef`, `AsyncFunctionDef`, or `ClassDef` |
+
+## Returns
+
+| Value | When |
+|-------|------|
+| `str` | The node has a leading string literal (docstring) |
+| `None` | The node has no docstring, or the first statement is not a string expression |
+
+## Notes
+- Works on any `ast.AST` node, but only `Module`, `FunctionDef`, `AsyncFunctionDef`, and `ClassDef` nodes can realistically contain docstrings per Python conventions.
+- Strips surrounding quotes — returns the raw string content, not the literal source.
+- Equivalent to calling `ast.get_docstring(node)` from the standard library.
+
+**Example:**
+
+```python example.py
+import ast
+
+# Inline implementation of get_docstring
+def get_docstring(node: ast.AST) -> "str | None":
+    """Extract docstring from a node if present."""
+    if not isinstance(node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return None
+    if not node.body:
+        return None
+    first_stmt = node.body[0]
+    if isinstance(first_stmt, ast.Expr) and isinstance(first_stmt.value, ast.Constant):
+        value = first_stmt.value.value
+        if isinstance(value, str):
+            return value
+    return None
+
+
+# --- Example 1: Extract docstring from a function ---
+function_source = '''
+def greet(name: str) -> str:
+    """Return a friendly greeting for the given name."""
+    return f"Hello, {name}!"
+'''
+
+function_tree = ast.parse(function_source)
+func_node = function_tree.body[0]  # The FunctionDef node
+
+func_docstring = get_docstring(func_node)
+print("Function docstring:", func_docstring)
+# Output: Function docstring: Return a friendly greeting for the given name.
+
+
+# --- Example 2: Extract docstring from a class ---
+class_source = '''
+class UserAccount:
+    """Represents a user account in the system."""
+
+    def __init__(self, user_id: str):
+        self.user_id = user_id
+'''
+
+class_tree = ast.parse(class_source)
+class_node = class_tree.body[0]  # The ClassDef node
+
+class_docstring = get_docstring(class_node)
+print("Class docstring:", class_docstring)
+# Output: Class docstring: Represents a user account in the system.
+
+
+# --- Example 3: Returns None when no docstring is present ---
+no_doc_source = '''
+def add(a: int, b: int) -> int:
+    return a + b
+'''
+
+no_doc_tree = ast.parse(no_doc_source)
+no_doc_node = no_doc_tree.body[0]
+
+result = get_docstring(no_doc_node)
+print("No docstring result:", result)
+# Output: No docstring result: None
+
+
+# --- Example 4: Extract docstring from a module ---
+module_source = '''
+"""
+Authentication utilities for the payments service.
+Handles token validation and session management.
+"""
+
+import os
+'''
+
+module_tree = ast.parse(module_source)
+module_docstring = get_docstring(module_tree)
+print("Module docstring:", module_docstring)
+# Output: Module docstring:
+#         Authentication utilities for the payments service.
+#         Handles token validation and session management.
+```
+
+### `get_type_annotation`
+
+```python
+def get_type_annotation(annotation: ast.AST | None) -> str | None
+```
+
+Use this to convert a Python AST type annotation node into its human-readable string representation — ideal for documentation generators, code analyzers, or any tool that needs to display type hints as readable text.
+
+Returns `None` if the annotation is `None` or cannot be resolved. Returns a string like `"str"`, `"int"`, `"List[str]"`, or `"Optional[int]"` for valid annotations.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `annotation` | `ast.AST \| None` | No | An AST node representing a type annotation, typically from `ast.parse()` or a function argument's `.annotation` attribute. Pass `None` to safely handle unannotated parameters. |
+
+## Returns
+
+| Condition | Return Value |
+|-----------|-------------|
+| `annotation` is `None` | `None` |
+| Valid AST annotation node | `str` — the human-readable type string (e.g. `"int"`, `"List[str]"`) |
+| Unresolvable/complex node | `None` |
+
+**Example:**
+
+```python example.py
+import ast
+
+# Inline implementation of get_type_annotation
+def get_type_annotation(annotation: ast.AST | None) -> str | None:
+    """Convert type annotation AST to string."""
+    if annotation is None:
+        return None
+    try:
+        return ast.unparse(annotation)
+    except Exception:
+        return None
+
+# --- Example 1: Simple type annotations from a function signature ---
+source_code = """
+def greet(name: str, age: int, scores: list[float]) -> bool:
+    pass
+"""
+
+tree = ast.parse(source_code)
+func_def = tree.body[0]  # The function definition node
+
+print("=== Function argument annotations ===")
+for arg in func_def.args.args:
+    annotation_str = get_type_annotation(arg.annotation)
+    print(f"  {arg.arg}: {annotation_str}")
+# Output:
+#   name: str
+#   age: int
+#   scores: list[float]
+
+print("\n=== Return annotation ===")
+return_annotation = get_type_annotation(func_def.returns)
+print(f"  -> {return_annotation}")
+# Output:
+#   -> bool
+
+# --- Example 2: Complex/generic annotations ---
+complex_source = """
+def process(
+    data: dict[str, list[int]],
+    callback: "Callable[[int], None]",
+    value: int | None = None
+) -> tuple[bool, str]:
+    pass
+"""
+
+complex_tree = ast.parse(complex_source)
+complex_func = complex_tree.body[0]
+
+print("\n=== Complex annotations ===")
+for arg in complex_func.args.args:
+    annotation_str = get_type_annotation(arg.annotation)
+    print(f"  {arg.arg}: {annotation_str}")
+# Output:
+#   data: dict[str, list[int]]
+#   callback: 'Callable[[int], None]'
+#   value: int | None
+
+# --- Example 3: Handling None (unannotated parameters) ---
+unannotated_source = """
+def legacy_func(x, y, z: int):
+    pass
+"""
+
+unannotated_tree = ast.parse(unannotated_source)
+unannotated_func = unannotated_tree.body[0]
+
+print("\n=== Mixed annotated/unannotated parameters ===")
+for arg in unannotated_func.args.args:
+    annotation_str = get_type_annotation(arg.annotation)
+    label = annotation_str if annotation_str is not None else "(no annotation)"
+    print(f"  {arg.arg}: {label}")
+# Output:
+#   x: (no annotation)
+#   y: (no annotation)
+#   z: int
+```
+
+### `get_default_value`
+
+```python
+def get_default_value(default: ast.AST | None) -> str | None
+```
+
+Use this to extract a human-readable string representation of a Python function parameter's default value from its AST node — ideal for documentation generators, code analyzers, or introspection tools.
+
+When parsing Python source code with the `ast` module, default values are stored as AST nodes. This function converts those nodes back into readable strings (e.g., `"42"`, `"'hello'"`, `"None"`). Returns `None` if no default value exists.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `default` | `ast.AST \| None` | No | An AST node representing a parameter's default value, or `None` if the parameter has no default |
+
+### Returns
+
+| Condition | Return Value |
+|-----------|-------------|
+| `default` is `None` | `None` |
+| `default` is a valid AST node | `str` — the unparsed source representation of the default value (e.g., `"42"`, `"True"`, `"'hello'"`, `"[1, 2, 3]"`) |
+
+### Notes
+- Uses `ast.unparse()` internally (requires Python 3.9+)
+- Handles complex defaults like list literals, dict literals, and function calls
+- Safe to call with `None` — will not raise an exception
+
+**Example:**
+
+```python example.py
+import ast
+
+# Inline implementation of get_default_value
+def get_default_value(default: ast.AST | None) -> str | None:
+    """Convert default value AST to string."""
+    if default is None:
+        return None
+    return ast.unparse(default)
+
+# Helper: parse a function and extract its argument defaults
+def extract_defaults(source: str) -> dict:
+    tree = ast.parse(source)
+    func = tree.body[0]  # First function definition
+    args = func.args
+
+    # Pair each argument with its default (defaults are right-aligned)
+    all_args = args.args
+    num_defaults = len(args.defaults)
+    offset = len(all_args) - num_defaults
+
+    results = {}
+    for i, arg in enumerate(all_args):
+        default_node = args.defaults[i - offset] if i >= offset else None
+        results[arg.arg] = get_default_value(default_node)
+
+    return results
+
+# Example function source with various default types
+sample_code = """
+def create_user(
+    name,
+    role='admin',
+    max_retries=3,
+    tags=['read', 'write'],
+    config={'timeout': 30},
+    active=True,
+    score=9.5,
+    callback=None
+):
+    pass
+"""
+
+try:
+    defaults = extract_defaults(sample_code)
+
+    for param, default in defaults.items():
+        print(f"  {param}: default = {repr(default)}")
+
+    # Expected output:
+    #   name:        default = None          (no default)
+    #   role:        default = "'admin'"
+    #   max_retries: default = '3'
+    #   tags:        default = "['read', 'write']"
+    #   config:      default = "{'timeout': 30}"
+    #   active:      default = 'True'
+    #   score:       default = '9.5'
+    #   callback:    default = 'None'
+
+except SyntaxError as e:
+    print(f"Failed to parse source: {e}")
+except AttributeError as e:
+    print(f"Unexpected AST structure: {e}")
+```
+
+### `extract_parameters`
+
+```python
+def extract_parameters(args: ast.arguments) -> list[dict[str, Any]]
+```
+
+Use this to convert Python AST function arguments into a structured list of parameter metadata — ideal for building documentation generators, code analyzers, or introspection tools.
+
+Given an `ast.arguments` object (obtained by parsing Python source code), this function returns a list of dictionaries, each describing one parameter: its name, type annotation (if any), and default value (if any).
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `ast.arguments` | ✅ Yes | The arguments node from a parsed Python function definition, typically accessed via `node.args` on a `FunctionDef` AST node |
+
+### Returns
+
+Returns a `list[dict[str, Any]]` where each dictionary represents one parameter. Each dict typically contains:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `name` | `str` | The parameter name |
+| `annotation` | `str \| None` | The type annotation as a string, or `None` if not annotated |
+| `default` | `Any \| None` | The default value, or `None` if no default is provided |
+
+Returns an **empty list** if the function has no parameters.
+
+**Example:**
+
+```python example.py
+import ast
+from typing import Any
+
+# ── Inline implementation of extract_parameters ──────────────────────────────
+
+def extract_parameters(args: ast.arguments) -> list[dict[str, Any]]:
+    """Extract parameters from function arguments."""
+    params: list[dict[str, Any]] = []
+
+    # Calculate offset for defaults (defaults only cover the LAST n args)
+    all_args = args.args
+    defaults_offset = len(all_args) - len(args.defaults)
+
+    for i, arg in enumerate(all_args):
+        # Resolve annotation to a readable string
+        annotation: str | None = None
+        if arg.annotation is not None:
+            annotation = ast.unparse(arg.annotation)
+
+        # Resolve default value if present
+        default: Any = None
+        default_index = i - defaults_offset
+        if default_index >= 0:
+            default = ast.literal_eval(args.defaults[default_index])
+
+        params.append({
+            "name": arg.arg,
+            "annotation": annotation,
+            "default": default,
+        })
+
+    return params
+
+
+# ── Example: parse a realistic function and extract its parameters ────────────
+
+SOURCE_CODE = """
+def create_user(
+    username: str,
+    email: str,
+    age: int,
+    role: str = "viewer",
+    is_active: bool = True,
+    max_sessions: int = 3,
+):
+    pass
+"""
+
+try:
+    tree = ast.parse(SOURCE_CODE)
+
+    # Grab the first function definition in the module
+    func_def = next(
+        node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)
+    )
+
+    print(f"Extracting parameters from: {func_def.name}()\n")
+
+    parameters = extract_parameters(func_def.args)
+
+    for param in parameters:
+        annotation = param["annotation"] or "untyped"
+        default    = repr(param["default"]) if param["default"] is not None else "required"
+        print(f"  {param['name']:<15} type={annotation:<8}  default={default}")
+
+    # Expected output:
+    # Extracting parameters from: create_user()
+    #
+    #   username        type=str      default=required
+    #   email           type=str      default=required
+    #   age             type=int      default=required
+    #   role            type=str      default='viewer'
+    #   is_active       type=bool     default=True
+    #   max_sessions    type=int      default=3
+
+except SyntaxError as e:
+    print(f"Failed to parse source code: {e}")
+except StopIteration:
+    print("No function definition found in the source code.")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+### `build_signature`
+
+```python
+def build_signature(name: str, args: ast.arguments, returns: ast.AST | None, is_async: bool) -> str
+```
+
+Use this to reconstruct a human-readable function signature string from parsed AST components — useful when generating documentation, code analysis tools, or displaying function metadata without executing the code.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `str` | ✅ | The function name to include in the signature |
+| `args` | `ast.arguments` | ✅ | The parsed argument node from the AST, containing all parameter info (defaults, annotations, etc.) |
+| `returns` | `ast.AST \| None` | ✅ | The return type annotation node from the AST, or `None` if no return type is specified |
+| `is_async` | `bool` | ✅ | Whether to prefix the signature with `async def` instead of `def` |
+
+## Returns
+
+A formatted string representing the full function signature, e.g.:
+- `"def greet(name: str, age: int = 0) -> str"`
+- `"async def fetch(url: str, timeout: float = 30.0) -> dict"`
+- `"def run()"` (when no args or return type)
+
+**Example:**
+
+```python example.py
+import ast
+
+# Inline implementation of build_signature
+def build_signature(name: str, args: ast.arguments, returns: ast.AST | None, is_async: bool) -> str:
+    """Build the function signature as a string."""
+    prefix = "async def" if is_async else "def"
+
+    # Build argument list
+    arg_parts = []
+
+    # Calculate offset for defaults (defaults only apply to the last N positional args)
+    num_args = len(args.args)
+    num_defaults = len(args.defaults)
+    defaults_offset = num_args - num_defaults
+
+    for i, arg in enumerate(args.args):
+        arg_str = arg.arg
+
+        # Add type annotation if present
+        if arg.annotation:
+            arg_str += f": {ast.unparse(arg.annotation)}"
+
+        # Add default value if present
+        default_index = i - defaults_offset
+        if default_index >= 0:
+            default_val = ast.unparse(args.defaults[default_index])
+            arg_str += f" = {default_val}"
+
+        arg_parts.append(arg_str)
+
+    # Handle *args
+    if args.vararg:
+        vararg_str = f"*{args.vararg.arg}"
+        if args.vararg.annotation:
+            vararg_str += f": {ast.unparse(args.vararg.annotation)}"
+        arg_parts.append(vararg_str)
+
+    # Handle **kwargs
+    if args.kwarg:
+        kwarg_str = f"**{args.kwarg.arg}"
+        if args.kwarg.annotation:
+            kwarg_str += f": {ast.unparse(args.kwarg.annotation)}"
+        arg_parts.append(kwarg_str)
+
+    args_str = ", ".join(arg_parts)
+
+    # Build return annotation
+    return_str = ""
+    if returns:
+        return_str = f" -> {ast.unparse(returns)}"
+
+    return f"{prefix} {name}({args_str}){return_str}"
+
+
+def demo():
+    # --- Example 1: Simple sync function with typed args and return ---
+    source_1 = "def greet(name: str, age: int = 0) -> str: pass"
+    tree_1 = ast.parse(source_1)
+    func_1 = tree_1.body[0]  # type: ignore[index]
+
+    sig_1 = build_signature(
+        name=func_1.name,
+        args=func_1.args,
+        returns=func_1.returns,
+        is_async=False
+    )
+    print("Example 1:", sig_1)
+    # Output: def greet(name: str, age: int = 0) -> str
+
+    # --- Example 2: Async function with *args and **kwargs ---
+    source_2 = "async def fetch(url: str, timeout: float = 30.0, *args, **kwargs) -> dict: pass"
+    tree_2 = ast.parse(source_2)
+    func_2 = tree_2.body[0]  # type: ignore[index]
+
+    sig_2 = build_signature(
+        name=func_2.name,
+        args=func_2.args,
+        returns=func_2.returns,
+        is_async=True
+    )
+    print("Example 2:", sig_2)
+    # Output: async def fetch(url: str, timeout: float = 30.0, *args, **kwargs) -> dict
+
+    # --- Example 3: No args, no return type ---
+    source_3 = "def run(): pass"
+    tree_3 = ast.parse(source_3)
+    func_3 = tree_3.body[0]  # type: ignore[index]
+
+    sig_3 = build_signature(
+        name=func_3.name,
+        args=func_3.args,
+        returns=func_3.returns,
+        is_async=False
+    )
+    print("Example 3:", sig_3)
+    # Output: def run()
+
+    # --- Example 4: Async function with no return annotation ---
+    source_4 = "async def process(data: list, batch_size: int = 100): pass"
+    tree_4 = ast.parse(source_4)
+    func_4 = tree_4.body[0]  # type: ignore[index]
+
+    sig_4 = build_signature(
+        name=func_4.name,
+        args=func_4.args,
+        returns=func_4.returns,
+        is_async=True
+    )
+    print("Example 4:", sig_4)
+    # Output: async def process(data: list, batch_size: int = 100)
+
+
+demo()
+```
+
+### `extract_function`
+
+```python
+def extract_function(node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str, parent_class: str | None) -> dict[str, Any]
+```
+
+Use this to extract structured metadata from a Python function or method AST node — including its name, signature, docstring, decorators, and source location — for use in code analysis, documentation generation, or static analysis tooling.
+
+Given an AST node representing a function or async function, this returns a dictionary containing all relevant metadata about that function, ready for further processing or storage.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `node` | `ast.FunctionDef \| ast.AsyncFunctionDef` | Yes | The AST node representing the function or async function to extract metadata from |
+| `file_path` | `str` | Yes | Absolute or relative path to the source file containing the function, used for source location tracking |
+| `parent_class` | `str \| None` | No | Name of the enclosing class if this is a method; `None` for top-level functions |
+
+## Returns
+
+A `dict[str, Any]` containing extracted function metadata. Typical keys include:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `name` | `str` | The function's name |
+| `file_path` | `str` | Path to the source file |
+| `parent_class` | `str \| None` | Enclosing class name, or `None` |
+| `is_async` | `bool` | Whether the function is defined with `async def` |
+| `docstring` | `str \| None` | The function's docstring, or `None` if absent |
+| `decorators` | `list[str]` | List of decorator names applied to the function |
+| `lineno` | `int` | Line number where the function is defined |
+| `args` | `list[str]` | List of argument names |
+
+**Example:**
+
+```python example.py
+import ast
+from typing import Any
+
+# Inline implementation of extract_function
+def extract_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    file_path: str,
+    parent_class: str | None = None
+) -> dict[str, Any]:
+    """Extract structured metadata from a function or method AST node."""
+    docstring = ast.get_docstring(node)
+
+    decorators = []
+    for dec in node.decorator_list:
+        if isinstance(dec, ast.Name):
+            decorators.append(dec.id)
+        elif isinstance(dec, ast.Attribute):
+            decorators.append(f"{dec.value.id}.{dec.attr}")  # type: ignore[attr-defined]
+        else:
+            decorators.append(ast.unparse(dec))
+
+    args = [arg.arg for arg in node.args.args]
+
+    return {
+        "name": node.name,
+        "file_path": file_path,
+        "parent_class": parent_class,
+        "is_async": isinstance(node, ast.AsyncFunctionDef),
+        "docstring": docstring,
+        "decorators": decorators,
+        "lineno": node.lineno,
+        "args": args,
+    }
+
+
+# --- Example: parse a source snippet and extract function metadata ---
+
+source_code = '''
+import asyncio
+
+class PaymentService:
+    @staticmethod
+    async def process_payment(user_id: str, amount: float, currency: str = "USD") -> dict:
+        """Process a payment for the given user.
+
+        Validates the amount and submits to the payment gateway.
+        """
+        return {"status": "ok", "user_id": user_id, "amount": amount}
+
+def health_check():
+    """Return service health status."""
+    return {"healthy": True}
+'''
+
+try:
+    tree = ast.parse(source_code)
+
+    extracted = []
+
+    for node in ast.walk(tree):
+        # Extract top-level functions
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Check if it's a method inside a class
+            parent_class = None
+            for parent in ast.walk(tree):
+                if isinstance(parent, ast.ClassDef):
+                    for item in parent.body:
+                        if item is node:
+                            parent_class = parent.name
+
+            result = extract_function(
+                node=node,
+                file_path="src/services/payment_service.py",
+                parent_class=parent_class,
+            )
+            extracted.append(result)
+
+    for func_meta in extracted:
+        print(f"\nFunction: {func_meta['name']}")
+        print(f"  File:         {func_meta['file_path']}")
+        print(f"  Class:        {func_meta['parent_class']}")
+        print(f"  Async:        {func_meta['is_async']}")
+        print(f"  Args:         {func_meta['args']}")
+        print(f"  Decorators:   {func_meta['decorators']}")
+        print(f"  Line:         {func_meta['lineno']}")
+        print(f"  Docstring:    {func_meta['docstring']!r}")
+
+    # Expected output:
+    # Function: process_payment
+    #   File:         src/services/payment_service.py
+    #   Class:        PaymentService
+    #   Async:        True
+    #   Args:         ['user_id', 'amount', 'currency']
+    #   Decorators:   ['staticmethod']
+    #   Line:         5
+    #   Docstring:    'Process a payment for the given user.\n\n        Validates...'
+    #
+    # Function: health_check
+    #   File:         src/services/payment_service.py
+    #   Class:        None
+    #   Async:        False
+    #   Args:         []
+    #   Decorators:   []
+    #   Line:         12
+    #   Docstring:    'Return service health status.'
+
+except SyntaxError as e:
+    print(f"Failed to parse source: {e}")
+except Exception as e:
+    print(f"Extraction failed: {e}")
+```
+
+### `extract_class`
+
+```python
+def extract_class(node: ast.ClassDef, file_path: str) -> list[dict[str, Any]]
+```
+
+Use this to parse a Python AST `ClassDef` node and extract structured metadata about a class and all its methods into a flat list of dictionaries.
+
+Each dictionary in the returned list represents either the class itself or one of its methods, making it easy to index, search, or analyze Python source code programmatically.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `node` | `ast.ClassDef` | Yes | The AST node representing the class definition, obtained by parsing Python source code |
+| `file_path` | `str` | Yes | The file path of the source file containing the class, stored in the returned metadata |
+
+## Returns
+
+Returns a `list[dict[str, Any]]` where:
+- **First element** is always the class-level metadata (name, docstring, base classes, line number, file path, etc.)
+- **Subsequent elements** are method-level metadata entries, one per method defined in the class
+- Returns an **empty list** if the node contains no extractable information
+
+### Example Return Shape
+```python
+[
+  {
+    "type": "class",
+    "name": "MyClass",
+    "file_path": "src/models.py",
+    "lineno": 10,
+    "docstring": "A sample class.",
+    "bases": ["BaseModel"]
+  },
+  {
+    "type": "method",
+    "name": "my_method",
+    "file_path": "src/models.py",
+    "lineno": 15,
+    "docstring": "Does something.",
+    "args": ["self", "value"]
+  }
+]
+```
+
+**Example:**
+
+```python example.py
+import ast
+from typing import Any
+
+# ── Inline implementation of extract_class ────────────────────────────────────
+
+def extract_class(node: ast.ClassDef, file_path: str) -> list[dict[str, Any]]:
+    """Extract a class and its methods into a flat list of metadata dicts."""
+    results: list[dict[str, Any]] = []
+
+    # Extract class-level metadata
+    class_entry: dict[str, Any] = {
+        "type": "class",
+        "name": node.name,
+        "file_path": file_path,
+        "lineno": node.lineno,
+        "docstring": ast.get_docstring(node) or "",
+        "bases": [
+            (base.id if isinstance(base, ast.Name) else ast.unparse(base))
+            for base in node.bases
+        ],
+    }
+    results.append(class_entry)
+
+    # Extract each method defined directly in the class body
+    for item in node.body:
+        if isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
+            method_entry: dict[str, Any] = {
+                "type": "async_method" if isinstance(item, ast.AsyncFunctionDef) else "method",
+                "name": item.name,
+                "file_path": file_path,
+                "lineno": item.lineno,
+                "docstring": ast.get_docstring(item) or "",
+                "args": [arg.arg for arg in item.args.args],
+            }
+            results.append(method_entry)
+
+    return results
+
+
+# ── Example usage ─────────────────────────────────────────────────────────────
+
+SOURCE_CODE = '''
+class PaymentProcessor(BaseProcessor):
+    """Handles payment transactions for the billing system."""
+
+    def __init__(self, api_key: str, timeout: int = 30):
+        """Initialize with API credentials."""
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def charge(self, amount: float, currency: str = "USD") -> dict:
+        """Charge a customer the given amount."""
+        return {"status": "ok", "amount": amount, "currency": currency}
+
+    async def refund(self, transaction_id: str) -> bool:
+        """Asynchronously refund a transaction."""
+        return True
+'''
+
+def main() -> None:
+    try:
+        tree = ast.parse(SOURCE_CODE)
+
+        # Find the first ClassDef node in the parsed tree
+        class_node = next(
+            node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)
+        )
+
+        results = extract_class(class_node, file_path="src/billing/processor.py")
+
+        print(f"Extracted {len(results)} entries:\n")
+        for entry in results:
+            print(f"  [{entry['type'].upper()}] {entry['name']!r}")
+            print(f"    file   : {entry['file_path']}")
+            print(f"    line   : {entry['lineno']}")
+            print(f"    doc    : {entry['docstring']!r}")
+            if entry["type"] == "class":
+                print(f"    bases  : {entry['bases']}")
+            else:
+                print(f"    args   : {entry['args']}")
+            print()
+
+        # Expected output:
+        # Extracted 4 entries:
+        #
+        #   [CLASS]  'PaymentProcessor'
+        #     file   : src/billing/processor.py
+        #     line   : 2
+        #     doc    : 'Handles payment transactions for the billing system.'
+        #     bases  : ['BaseProcessor']
+        #
+        #   [METHOD] '__init__'
+        #     args   : ['self', 'api_key', 'timeout']
+        #
+        #   [METHOD] 'charge'
+        #     args   : ['self', 'amount', 'currency']
+        #
+        #   [ASYNC_METHOD] 'refund'
+        #     args   : ['self', 'transaction_id']
+
+    except StopIteration:
+        print("Error: No class definition found in the source code.")
+    except SyntaxError as exc:
+        print(f"Error: Failed to parse source code — {exc}")
+
+main()
+```
+
+### `scan_file`
+
+```python
+def scan_file(file_path: str) -> dict[str, Any]
+```
+
+Use this to extract all API elements from a Python source file — functions, classes, methods, imports, and metadata — in a single structured dictionary.
+
+Ideal for building documentation generators, code analysis tools, static analyzers, or any workflow that needs to introspect a Python file programmatically.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `file_path` | `str` | ✅ Yes | Absolute or relative path to the `.py` file to scan |
+
+## Returns
+
+Returns a `dict[str, Any]` containing extracted API elements from the file. Typical keys include:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `functions` | `list` | Top-level function definitions found in the file |
+| `classes` | `list` | Class definitions, including their methods and attributes |
+| `imports` | `list` | All import statements detected |
+| `docstrings` | `dict` | Docstrings mapped to their parent element |
+| `errors` | `list` | Any parse errors encountered during scanning |
+
+> **Note:** Returns an empty structure (not `None`) if the file exists but contains no API elements. Raises `FileNotFoundError` if the path does not exist, and `SyntaxError` if the file cannot be parsed.
+
+**Example:**
+
+```python example.py
+import ast
+import os
+from typing import Any
+
+# Inline implementation of scan_file — no external imports needed
+def scan_file(file_path: str) -> dict[str, Any]:
+    """Scan a Python file and extract all API elements."""
+    result: dict[str, Any] = {
+        "file": file_path,
+        "functions": [],
+        "classes": [],
+        "imports": [],
+        "docstrings": {},
+        "errors": [],
+    }
+
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"No such file: '{file_path}'")
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        source = f.read()
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        result["errors"].append(str(e))
+        return result
+
+    for node in ast.walk(tree):
+        # Extract top-level functions
+        if isinstance(node, ast.FunctionDef):
+            func_info = {
+                "name": node.name,
+                "args": [arg.arg for arg in node.args.args],
+                "lineno": node.lineno,
+            }
+            result["functions"].append(func_info)
+            docstring = ast.get_docstring(node)
+            if docstring:
+                result["docstrings"][node.name] = docstring
+
+        # Extract classes and their methods
+        elif isinstance(node, ast.ClassDef):
+            methods = [
+                n.name for n in ast.walk(node) if isinstance(n, ast.FunctionDef)
+            ]
+            class_info = {
+                "name": node.name,
+                "methods": methods,
+                "lineno": node.lineno,
+            }
+            result["classes"].append(class_info)
+            docstring = ast.get_docstring(node)
+            if docstring:
+                result["docstrings"][node.name] = docstring
+
+        # Extract imports
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                result["imports"].append({"module": alias.name, "alias": alias.asname})
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                result["imports"].append({
+                    "module": f"{node.module}.{alias.name}",
+                    "alias": alias.asname,
+                })
+
+    return result
+
+
+# --- Create a temporary sample Python file to scan ---
+sample_code = '''
+"""A sample module for demonstration."""
+import os
+import sys
+from pathlib import Path
+
+class DataProcessor:
+    """Processes incoming data records."""
+
+    def __init__(self, config: dict):
+        self.config = config
+
+    def process(self, data: list) -> list:
+        """Run the processing pipeline."""
+        return [item.strip() for item in data]
+
+def load_config(path: str) -> dict:
+    """Load configuration from a file path."""
+    return {"path": path, "debug": False}
+
+def validate(value: str) -> bool:
+    return len(value) > 0
+'''
+
+sample_file = "/tmp/sample_module.py"
+with open(sample_file, "w") as f:
+    f.write(sample_code)
+
+# --- Run scan_file and display results ---
+try:
+    api_data = scan_file(sample_file)
+
+    print(f"📄 Scanned file : {api_data['file']}")
+    print(f"\n📦 Classes found ({len(api_data['classes'])}):")
+    for cls in api_data["classes"]:
+        print(f"  - {cls['name']} (line {cls['lineno']}) | methods: {cls['methods']}")
+
+    print(f"\n⚙️  Functions found ({len(api_data['functions'])}):")
+    for fn in api_data["functions"]:
+        print(f"  - {fn['name']}({', '.join(fn['args'])}) at line {fn['lineno']}")
+
+    print(f"\n📥 Imports found ({len(api_data['imports'])}):")
+    for imp in api_data["imports"]:
+        alias = f" as {imp['alias']}" if imp["alias"] else ""
+        print(f"  - {imp['module']}{alias}")
+
+    print(f"\n📝 Docstrings captured: {list(api_data['docstrings'].keys())}")
+    print(f"❌ Errors: {api_data['errors'] or 'None'}")
+
+    # Expected output:
+    # 📄 Scanned file : /tmp/sample_module.py
+    # 📦 Classes found (1):
+    #   - DataProcessor (line 6) | methods: ['__init__', 'process']
+    # ⚙️  Functions found (4):
+    #   - __init__(self, config) at line 9
+    #   - process(self, data) at line 12
+    #   - load_config(path) at line 16
+    #   - validate(value) at line 20
+    # 📥 Imports found (4):
+    #   - os
+    #   - sys
+    #   - pathlib.Path
+    # 📝 Docstrings captured: ['DataProcessor', 'process', 'load_config']
+    # ❌ Errors: None
+
+except FileNotFoundError as e:
+    print(f"File error: {e}")
+except SyntaxError as e:
+    print(f"Parse error in file: {e}")
+finally:
+    # Clean up temp file
+    if os.path.exists(sample_file):
+        os.remove(sample_file)
+```
+