python-sdk/docs/tools/code.md

Code Tool

Symbol and structure operations for source code (HIP-0300 operator).

Installation

pip install hanzo-tools-code

Overview

The code tool handles all code analysis and transformation operations:

Action	Signature	Effect
parse	(Path | Text, lang?) → AST	PURE
serialize	AST → Text	PURE
symbols	(Path | AST, kind?) → [Symbol]	PURE
definition	(Path, Position) → [Location]	DETERMINISTIC
references	(Path, Position) → [Location]	DETERMINISTIC
transform	(Path | Text, kind, params) → Patch	PURE
summarize	(Diff | Log | Report) → Summary	PURE

Actions

parse

Parse source code into an Abstract Syntax Tree using tree-sitter.

code(action="parse", path="/src/main.py")
# Returns: {tree: {...}, lang: "python", node_count: 142}

code(action="parse", text="def foo(): pass", lang="python")
# Returns: {tree: {...}, lang: "python", node_count: 5}

Parameters:

• path (str, optional): Path to source file
• text (str, optional): Source code text (provide one of path or text)
• lang (str, optional): Language hint (auto-detected from extension)

serialize

Convert AST back to source code.

code(action="serialize", tree=ast_tree, lang="python")
# Returns: {text: "def foo(): pass", size: 16}

symbols

Extract symbols (functions, classes, variables) from code.

code(action="symbols", path="/src/main.py")
# Returns: {symbols: [{name: "foo", kind: "function", line: 1}, ...]}

code(action="symbols", path="/src/main.py", kind="class")
# Returns: {symbols: [{name: "MyClass", kind: "class", line: 10}]}

Parameters:

• path (str, optional): Path to source file
• text (str, optional): Source code text
• kind (str, optional): Filter by symbol kind (function, class, variable, etc.)

definition

Find the definition of a symbol at a position (requires LSP).

code(action="definition", path="/src/main.py", line=42, col=10)
# Returns: {locations: [{uri: "file:///src/utils.py", line: 15, col: 0}]}

references

Find all references to a symbol (requires LSP).

code(action="references", path="/src/main.py", line=42, col=10)
# Returns: {locations: [{uri: "...", line: ..., col: ...}, ...], count: 7}

transform

Apply a transformation and produce a Patch (PURE - no side effects).

# Rename a symbol
code(action="transform", path="/src/main.py", kind="rename",
     old_name="authenticate", new_name="verify_user")
# Returns: {patch: [...], base_hash: "sha256:abc...", new_hash: "sha256:def...", changes_count: 5}

# Extract a function
code(action="transform", path="/src/main.py", kind="extract",
     start_line=10, end_line=20, new_name="helper_function")
# Returns: {patch: [...], base_hash: "...", new_hash: "..."}

Transform Kinds:

• rename - Rename a symbol (old_name, new_name)
• extract - Extract code to function (start_line, end_line, new_name)
• inline - Inline a function/variable
• move - Move symbol to another file

summarize

Compress diff/log/report into actionable summary.

code(action="summarize", diff=patch_content)
# Returns: {summary: "Renamed authenticate to verify_user in 5 locations",
#           risks: ["Breaking change for external callers"],
#           next_actions: ["Update API documentation", "Run integration tests"]}

code(action="summarize", log=[{"sha": "abc", "message": "..."}])
# Returns: {summary: "3 commits: added auth, fixed bug, updated tests", ...}

Transform vs Apply

The code.transform action is PURE - it produces a Patch value without modifying files. To apply the patch:

# 1. Generate transform (PURE)
result = code(action="transform", path="/src/main.py", kind="rename",
              old_name="foo", new_name="bar")

# 2. Review the patch
print(result["patch"])
print(result["summary"])

# 3. Apply with precondition (EFFECT)
fs(action="patch", path="/src/main.py", patch=result["patch"],
   base_hash=result["base_hash"])  # Fails if file changed

Language Support

Tree-sitter languages supported:

• Python, JavaScript, TypeScript, Rust, Go, C, C++, Java
• JSON, YAML, TOML, Markdown, HTML, CSS

Languages auto-detected from file extensions.

See Also

• HIP-0300 - Unified Tools Architecture
• Filesystem Tool - For applying patches with fs.patch
• LSP Tool - For additional semantic operations
• Refactor Tool - High-level refactoring operations