Forem: Herrington Darkholme

ast-grep 0.42: The Answer to Code Searching

Herrington Darkholme — Mon, 16 Mar 2026 22:18:30 +0000

After a long journey through the galaxy of AST manipulation, ast-grep has arrived at version 0.42 — the answer to the ultimate question of code searching, linting, and rewriting.

If Douglas Adams taught us anything, it's that the answer to life, the universe, and everything is 42. We'd like to think ast-grep 0.42 lives up to its number: this release packs powerful new features that answer some of the most requested questions from our community.

Don't panic — let's dive in.

Parameterized Utilities (Experimental)

Parameterized utilities are experimental. The current implementation is hacky, dirty, and quick — a prototype to gather real-world feedback. The API, behavior, and semantics may change, break, or even be removed entirely in future releases. That said, we encourage adventurous users to try it out! Please report bugs and share your feedback at ast-grep/ast-grep.

The biggest feature in this release has landed: parameterized utilities. Global utility rules in ast-grep let you define reusable rule components shared across your project, but previously they were static — you couldn't customize them for different contexts. Now, global utilities can accept arguments, making them far more flexible and reducing duplication in your rule configurations.

The Problem

Global utilities are reusable across files, but they couldn't be customized — you'd copy-paste the same structure over and over, changing only a name or a pattern.

Say you want to audit logging calls that pass a string literal as an argument. One rule bans console.log with string literals in production code, another flags logger.error with hardcoded messages. They have different severities and messages, so they must be separate rules — but without parameterization, each duplicates the entire rule structure:

# rules/audit-logging.yml
id: no-console-string
language: TypeScript
rule:
  pattern: $OBJ.$METHOD($$$ARGS)
  all:
    - has:
        kind: member_expression
        has:
          field: object
          regex: ^console$     # <--- console
    - has:
        field: arguments
        has:
          kind: string
---
id: no-hardcoded-logger
language: TypeScript
rule:
  pattern: $OBJ.$METHOD($$$ARGS)
  all:
    - has:
        kind: member_expression
        has:
          field: object
          regex: ^logger$      # <--- logger
    - has:
        field: arguments
        has:
          kind: string
# the entire rule body is identical — only this one line differs!

On top of that, there was no way to export matched meta-variables from a global utility back to its caller. This caused inability to share captured meta-variables across files (#1297), parse errors when using global util variables in fix (#1766), and confusion about why global utils couldn't provide variables like local ones could (#1994).

Parameterized utilities solve both problems: they eliminate duplication and provide a well-defined interface for passing rules in and getting meta-variables back.

The Solution

Think of parameterized utilities as functions for your rules. You declare parameters in the utility name, and then pass arguments when you call it with matches:

Define a parameterized global utility in a file under your utils/ directory:

# utils/audit-log-call.yml
id: audit-log-call
arguments: [logger-rule]          # declare parameters
language: TypeScript
rule:
  pattern: $OBJ.$METHOD($$$ARGS)
  all:
    - has:
        kind: member_expression
        has:
          field: object
          matches: logger-rule    # use the parameter as a rule
    - has:
        field: arguments
        has:
          kind: string

Then call it from any rule by passing arguments via matches. Each argument is itself a rule, not just a string — so you can pass patterns, regex, or any composite rule:

# rules/audit-logging.yml
id: no-console-string
language: TypeScript
rule:
  matches:
    audit-log-call:
      logger-rule: { regex: ^console$ } # pass rule as arg
---
id: no-hardcoded-logger
language: TypeScript
rule:
  matches:
    audit-log-call:
      logger-rule: { regex: ^logger$ } # pass rule as arg

The entire deep rule structure is defined once in the utility. Each rule only specifies what differs — the logger object name.

Crucially, meta-variables captured inside argument rules are exported back to the caller. This solves the long-standing problem of global utilities not being able to provide meta-variables for fix.

Here's an example: the named-import utility matches an import statement and delegates source validation to an argument rule. The ban-lodash rule uses it to find lodash imports and rewrite them to lodash-es.

The highlighted lines show where arguments are declared and where they are used as matches targets inside the utility body:

# utils/named-import.yml — reusable utility for matching named imports
id: named-import
arguments: [source-rule, binding-rule]   # declare two param rule
language: TypeScript
rule:
  pattern: import { $BINDING } from "$SOURCE"
  all:
    - has:
        field: source
        has:
          kind: string_fragment
          matches: source-rule           # filter source with param
    - has:
        stopBy: end
        kind: identifier
        matches: binding-rule            # export $BINDING

The highlighted lines below show the caller passing concrete rules as arguments. Meta-variable $IMPORT_NAME defined here is exported back and usable in fix:

# rules/ban-lodash.yml — rewrites lodash imports to lodash-es
id: ban-lodash
language: TypeScript
rule:
  matches:
    named-import:
      source-rule: { regex: ^lodash$ }         # only match lodash import
      binding-rule: { pattern: $IMPORT_NAME }  # capture import in metavar
fix: import { $IMPORT_NAME } from "lodash-es"

When matching import { map } from "lodash", the utility's pattern captures $BINDING = map and $SOURCE = lodash internally, in a separate environment. Note that matches: binding-rule is called on the AST node corresponding to $BINDING (the identifier map), so the caller's argument pattern: $IMPORT_NAME matches that same node and captures $IMPORT_NAME = map — effectively exporting $BINDING under a new name.

The utility's own meta-variables stay isolated. Only meta-variables from argument rules are exported to the caller:

Meta-variable	Captured by	Visible in `ban-lodash`?
`$IMPORT_NAME`	argument rule (`binding-rule`)	Yes — available in `fix`, `constraints`, etc.
`$BINDING`	utility's internal pattern	No — isolated inside the utility
`$SOURCE`	utility's internal pattern	No — isolated inside the utility

$IMPORT_NAME is available in fix because it was captured by a caller-supplied argument rule. Without parameterized utilities, there was no mechanism to get any meta-variables out of a global utility at all.

The rule of thumb here is that a meta-variable like $IMPORT_NAME is only available if it appears in the same YAML file where you define it. Meta-variables defined in a different file (like $BINDING) are never visible to the caller.
If you can't see the $ definition in your rule file, you can't use it.

Key Usage Rules

Only global utility rules (separate YAML files in the utils/ directory with id, language, and rule) can declare parameters. Local utils: entries in rule config files remain zero-argument helpers.
All declared arguments must be provided at the call site — no optional parameters.
Arguments are rules, not strings. Each argument value is a full ast-grep rule object.
Meta-variable isolation: argument rules match in their own isolated scope. They don't read or write the caller's meta-variables during matching — exports happen only after the entire parameterized rule matches successfully.

Advanced: How It Works Under the Hood

Implementation details for the curious

Parameterized utilities are implemented with runtime binding frames rather than template expansion. The binding frames are stored in a thread-local variable and use unsafe code internally — the implementation is pragmatic rather than polished, which is part of why this feature is marked experimental. Performance may be suboptimal, especially with deeply nested parameterized calls. When a parameterized rule is called:

The matches reference pushes name -> rule bindings into a thread-local frame.
The stored rule body is matched directly against the target code.
When a bare matches: PARAM is encountered inside the body, it looks up the binding frame and matches the bound rule.

Name resolution for bare matches: NAME follows lexical scoping:

Current parameter binding (innermost scope)
Local utility
Global zero-argument rule

A parameter name shadows any same-named local or global utility.

Meta-variable isolation is a deliberate design choice. Argument rules match in a temporary, isolated MetaVarEnv. Any meta-variables they define are accumulated and exported back to the caller only after the entire parameterized rule matches. If exporting conflicts with the caller's existing bindings (e.g., the caller already bound $A to a different value), the whole parameterized call fails. Importantly, this failure does not trigger backtracking inside the parameterized rule — an any branch won't be retried just because a late export failed.

Kind inference is conservative. Internally, ast-grep computes a set of potential_kinds for each rule as a performance optimization — if a rule can only ever match call_expression nodes, ast-grep skips all other node kinds entirely. However, when kind inference reaches a matches: PARAM reference, it cannot know what kinds the caller will pass, so it returns None (meaning "any kind is possible"). This disables kind-based pruning for that rule. If you need precise pruning, add an explicit kind guard in the utility body or at the call site.

Cycle detection remains syntactic. ast-grep detects circular dependencies between utility rules at parse time — if rule A matches rule B and rule B matches rule A, ast-grep will report an error before any scanning happens, helping you catch buggy rules early. For parameterized utilities, parameter names are excluded from dependency edges during topological sorting. A utility cannot call itself through its argument rules, either directly or transitively.

More ESQuery-Style Selectors

In ast-grep 0.39, we introduced ESQuery-style kind selectors with combinators like >, +, and ~. In 0.42, we're expanding this with new pseudo-selectors that bring even more expressive power to your queries. See the tracking issue for the full ESQuery roadmap.

`:has(selector)`

Select nodes that contain descendants matching a given selector. :has also supports the > combinator to match only direct children.

kind: 'function_declaration:has(return_statement)'
# is equivalent to
kind: function_declaration
has:
  kind: return_statement
  stopBy: end

kind: 'call_expression:has(> identifier)'
# is equivalent to
kind: call_expression
has:
  kind: identifier

`:not(selector)`

Exclude nodes matching a selector. Perfect for filtering out unwanted matches.

# match expression statements that don't contain a call
kind: 'expression_statement:not(:has(> call_expression))'
# is equivalent to
kind: expression_statement
not:
  has:
    kind: call_expression

`:is(selector, moreSelector, ...)`

Match nodes against any one of several selectors — a concise way to express "or" logic. Previously, the comma operator (e.g. function_declaration, arrow_function) could only be used at the top level of a selector. :is lifts that restriction: you can now express "or" anywhere inside a compound selector.

# match return statements or variable declarations inside a block
kind: 'statement_block > :is(return_statement, lexical_declaration)'
# is equivalent to
any:
  - kind: return_statement
  - kind: lexical_declaration
inside:
  kind: statement_block

`:nth-child(An+B)` and `:nth-child(An+B of selector)`

Select nodes by their position among siblings, using the familiar An+B syntax. You can even combine it with an of selector clause to filter which siblings count. Both An+B and An+B of selector are supported.

These are equivalent to ast-grep's nthChild rule:

# match odd-positioned numbers: [①, 2, ③, 4, ⑤]
kind: 'array > number:nth-child(2n+1)'
# is equivalent to
kind: number
nthChild: 2n+1
inside:
  kind: array

# match the first number, skipping non-numbers: [a, ①, 2, 3]
kind: 'array > :nth-child(1 of number)'
# is equivalent to
nthChild:
  position: 1
  ofRule:
    kind: number
inside:
  kind: array

These pseudo-selectors compose naturally with the existing combinators. Together, they bring ast-grep's ESQuery support much closer to a full selector system, making complex structural queries concise and readable.

LSP: Diagnostics for Injected Languages

A subtle but important fix: the ast-grep Language Server now correctly scans injected languages for diagnostics.

Injected languages are code embedded within other code — for example, Sassdoc comments inside SCSS files, or SQL within template strings. The ast-grep CLI has supported scanning these injected sections for a while, but the LSP wasn't reporting diagnostics for them. This created a frustrating inconsistency: rules that worked perfectly on the command line would show no results in your editor.

With this fix, your editor integration (VSCode, Zed, Neovim, etc.) now surfaces diagnostics for injected language rules, just like the CLI does. No more switching to the terminal to catch violations in embedded code.

Next Steps

As the Hitchhiker's Guide reminds us, the hard part was never finding the answer — it was knowing the right question to ask. We hope ast-grep 0.42 helps you ask better questions about your code.

Thanks for reading! If you are interested in the new features, please try them out and let us know your feedback.

Happy Grepping, and don't forget your towel! 🚀

Agent Calculus: A Unified Framework for AI Agent Design

Herrington Darkholme — Fri, 16 Jan 2026 03:11:38 +0000

Abstract

This document presents a unified formal framework for understanding AI agents through a calculus-like model. We introduce the concept of entities as the fundamental unit of agent computation, and define a harness that manages the flow of entities between the LLM's context and the external world. This framework elegantly unifies disparate concepts such as skills, tools, memory, subagents, and dynamic context loading under a single coherent model.

1. Introduction & Motivation

The Problem

Modern AI agent systems involve numerous distinct concepts:

Tools: Functions the agent can call to interact with the world
Skills: Reusable prompt templates and workflows
Memory: Persistent state from previous interactions
Subagents: Spawned agents for subtasks
Dynamic context loading: Just-in-time injection of relevant information
System prompts: Static instructions and behavior definitions

These concepts are typically treated as separate mechanisms, leading to:

Conceptual fragmentation in agent design
Difficulty reasoning about agent behavior holistically
Lack of composability between different agent patterns

The Solution

We propose treating all inputs to an agent as entities that flow through a harness which manages:

Loading: Filtering and packing entities into the LLM's limited context
Execution: Handling LLM actions and returning new entities

This abstraction enables:

Unified reasoning about agent behavior
Compositional design patterns
Systematic approaches to context management
Formal analysis of multi-agent systems

2. Core Assumptions

To simplify our calculus, we make three foundational assumptions:

Assumption 1: Limited Context

LLM context windows are finite and constrained. Context is the primary scarce resource in agent systems.

Note: LLM's context window can be larger in future. For example,

a conditional memory lookup can spare more attention to longer context https://github.com/deepseek-ai/Engram?tab=readme-ov-file
Extending the Context of Pretrained LLMs by Dropping their Positional Embeddings (DroPE) https://pub.sakana.ai/DroPE/

Assumption 2: Static Capabilities

LLMs do not perform continual learning during inference. Their capabilities are fixed at deployment.

Note: this can be changed in future. So some routine context loading can be done by updating model weights

see Nested Learning: The Illusion of Deep Learning Architecture. https://abehrouz.github.io/files/NL.pdf

Assumption 3: LLM Homogeneity

For the purposes of this calculus, we treat different LLMs as interchangeable.

Note: In practice they differ, but this simplifies our model.

3. Fundamental Definitions

3.1 LLM as Pure Function

We model an LLM as a pure function:

LLM: Context → (Reasoning, Actions)

Inputs:

Context: The text and structured data directly accessible to the LLM

Outputs:

Reasoning: Internal thought process, chain-of-thought, analysis
Actions: Structured requests to interact with the world (tool calls, responses, queries)

The LLM has no direct access to anything outside its context. It cannot see files, networks, databases, or any other state unless that information is explicitly loaded into its context.

3.2 Context vs World

Context: The observable, directly accessible information within the LLM's attention window.

Limited in size (e.g., 128K tokens)
Directly influences LLM outputs
Managed by the harness

World: Everything outside the context that the agent might need.

File systems
Databases
APIs
Previous conversation history (not currently in context)
External knowledge bases

The harness acts as the bridge between Context and World.

3.3 Agent Decomposition

An agent is the composition of two components:

Agent = LLM + Harness

The LLM performs reasoning and generates actions.

The Harness manages the agent loop:

Loads entities into context
Executes actions in the world
Handles context window constraints

4. The Entity Abstraction

Core Insight: Everything that can be loaded into an LLM's context is an entity.

4.1 Entity Definition

An entity is a unit of information with:

Content: The actual data or text
Metadata: How it should be loaded, when it's relevant, its size

4.2 Entity Types by Loading Strategy

Entity Type	Content Nature	Loading Strategy	Example
System Prompt	Static	Preloaded	Agent role definition, rules
Tool Description	Static	Dynamic or preloaded	Function signature, usage docs
Skill	Static	Dynamic	Reusable prompt templates
Memory	Dynamic	Preloaded	Conversation summaries
User Input	Dynamic	Preloaded	Current user message
Tool Result	Dynamic	Dynamic	Data returned from actions

4.3 Entity Dimensions

Entities can be characterized along multiple dimensions:

1. Content Mutability

Static: Content doesn't change (tool definitions, skills)
Dynamic: Content changes during execution (memory, tool results)

2. Loading Time

Preloaded: Always in context (system prompt, current memory)
Dynamic: Loaded on-demand (skills when invoked, tool descriptions when relevant)

3. Verbosity Levels

Full: Complete content loaded
Summary: Condensed version (e.g., skill titles only)
Digest: Compressed representation (e.g., large tool results summarized)
Reference: Pointer only (content remains in world, accessed via actions)

4.4 Examples

Example: Tool as Entity

Entity: FileReadTool
  Content (full):
    Name: read_file
    Description: Reads contents of a file from disk
    Parameters:
      - path: string (absolute path)
      - offset: int (optional, start line)
      - limit: int (optional, number of lines)
    Returns: string (file contents)

  Content (summary):
    read_file: Read file contents

  Metadata:
    type: tool_description
    static: true
    loading: dynamic (loaded when file operations relevant)

Example: Memory as Entity

Entity: ConversationMemory
  Content (full):
    [Last 50 conversation turns with full context]

  Content (digest):
    Summary: User is implementing auth system for web app.
    Currently debugging JWT token validation.
    Tech stack: Node.js, Express, PostgreSQL.

  Metadata:
    type: memory
    static: false (updated after each turn)
    loading: preloaded
    compression: digest after 10 turns

Example: Skill as Entity

Entity: GitCommitSkill
  Content (full):
    # Git Commit Workflow
    1. Run git status to see changes
    2. Review git diff for staged changes
    3. Draft commit message following repo conventions
    4. Execute git commit with message
    5. Verify with git log

  Content (summary):
    GitCommitSkill: Create git commits following best practices

  Metadata:
    type: skill
    static: true
    loading: dynamic (loaded when user requests git commit)

5. The Harness

The harness is the orchestration layer that manages the agent loop. It has two core responsibilities:

5.1 Load Function

load: (Context, Entity, List[Entity]) → Context'

Purpose: Intelligently pack entities into the limited context window.

Inputs:

Context: Current context state
Entity: New entity to incorporate (e.g., fresh user input, tool result)
List[Entity]: Available entities that could be loaded

Output:

Context': Updated context ready for LLM consumption

Responsibilities:

Filtering: Select only relevant entities from available pool
Compression: Choose appropriate verbosity level for each entity
Ordering: Arrange entities for optimal LLM performance
Eviction: Remove or compress old entities if context is full

5.2 Execute Function

execute: (Action, World) → (Entity, World')

Purpose: Perform actions in the world and return results as entities.

Inputs:

Action: LLM-generated action (tool call, query, response)
World: Current world state

Outputs:

Entity: Result data packaged as an entity
World': Updated world state after action

Examples:

Action = read_file("config.json") → Entity = {type: "tool_result", content: "{...json...}"}
Action = spawn_subagent("research task") → Entity = {type: "subagent_result", content: "..."}
Action = respond("Done!") → Entity = {type: "agent_response", content: "Done!"}

5.3 Context Window Management

The load function implements sophisticated strategies to handle context constraints:

Strategy 1: Relevance Filtering

Only load entities relevant to current task:

if task involves file operations:
  load file-related tool descriptions
else:
  omit file tools (even if available)

Strategy 2: Progressive Compression

# Fresh tool result: load full content
load(entity=tool_result, verbosity=full)

# After LLM reasoning: compress it
load(entity=tool_result, verbosity=digest)

# After several turns: remove entirely if no longer relevant
omit(entity=tool_result)

Strategy 3: Hierarchical Summarization

# If 50 tools available:
Group into categories: [file_ops, network, database, ...]
Load only category summaries initially
Load full descriptions only when category selected

Strategy 4: Swap Full↔Digest

Context before LLM call:
  [system_prompt] [memory_digest] [tool_result_FULL] [user_input]

Context after LLM reasoning:
  [system_prompt] [memory_digest] [tool_result_DIGEST] [llm_reasoning] [new_action]

5.4 Atomic Load Operations

The load function is composed of atomic operations:

Operation	Purpose	Example
summarize	Reduce entity size	Compress 50 messages → 1 paragraph
elaborate	Add more context	Expand terse user input with clarifications
omit	Remove entity completely	Drop tool result from 10 turns ago
paraphrase	Rewrite for clarity	Standardize user input phrasing
group	Combine related entities	Bundle related tool descriptions

6. The Agent Loop

Now we can express the complete agent execution as a simple loop:

6.1 Pseudocode

def agent_loop(user_input, world):
    ctx = Context()
    entity = Entity(content=user_input, type="user_input")
    entities = discover_available_entities(world)  # tools, skills, memory, etc.

    while not should_stop(ctx):
        # LOAD PHASE
        # Pack relevant entities into context
        ctx = harness.load(ctx, entity, entities)

        # REASONING PHASE
        # LLM processes context and generates action
        reasoning, action = llm(ctx)

        # Add reasoning to context for continuity
        ctx = ctx.append(reasoning)

        # EXECUTION PHASE
        # Execute action in world, get result as new entity
        entity, world = harness.execute(action, world)

        # New entity becomes input for next iteration

    return ctx, world

6.2 Example Execution Trace

User: "Read config.json and fix the database port"

Turn 1

Load Phase:
  ctx = [system_prompt, memory_summary, file_tools, user_input]

LLM Phase:
  reasoning: "Need to read config.json first"
  action: read_file("config.json")

Execute Phase:
  entity: {type: "tool_result", content: "{\n  \"db_port\": 3306\n  ...\n}"}
  world: unchanged

Turn 2

Load Phase:
  ctx = [system_prompt, memory_summary, file_tools,
         tool_result_FULL, previous_reasoning, edit_tools]
  # Note: file tool result loaded in full for LLM to analyze

LLM Phase:
  reasoning: "Database port is 3306 but should be 5432 for PostgreSQL"
  action: edit_file("config.json", old="3306", new="5432")

Execute Phase:
  entity: {type: "tool_result", content: "Successfully edited config.json"}
  world: config.json modified

Turn 3

Load Phase:
  ctx = [system_prompt, memory_summary,
         previous_tool_result_DIGEST,  # compressed now!
         current_tool_result,
         previous_reasoning]
  # Note: first tool result compressed to save space

LLM Phase:
  reasoning: "Task complete. Config fixed."
  action: respond("Fixed! Changed database port from 3306 to 5432")

Execute Phase:
  entity: {type: "agent_response"}
  should_stop: true

7. Multi-Agent Design Patterns

Using the entity calculus, we can formally describe common agent patterns.

7.1 Pattern: Tool-Use Agent

Description: Agent with access to external tools.

Implementation:

entities = [
    Entity(system_prompt),
    Entity(memory),
    Entity(user_input),
    *[Entity(tool_desc) for tool in available_tools]
]

# Tools are just entities with:
# 1. Description (for LLM to understand)
# 2. Execution handler (for harness.execute)

Key Insight: Tools are simultaneously entities (their descriptions load into context) and actions (their implementations execute in world).

7.2 Pattern: Skill-Enhanced Agent

Description: Agent that can load predefined workflows on-demand.

Implementation:

# Skills available but not preloaded
skill_entities = [
    Entity(GitCommitSkill, loading="dynamic"),
    Entity(DebugWorkflow, loading="dynamic"),
    Entity(RefactorPattern, loading="dynamic")
]

# Harness.load uses semantic search:
if user_input mentions "commit" or "git":
    load(GitCommitSkill, verbosity=full)
else:
    load(GitCommitSkill, verbosity=summary)  # just title

Key Insight: Skills are entities loaded at different verbosity levels based on relevance.

7.3 Pattern: Subagent Spawning

Description: Agent delegates subtasks to other agents.

Implementation:

# Define subagent spawn as a tool
SubAgentTool = Tool(
    name="spawn_subagent",
    description="Create a new agent for a subtask",
    execute=lambda prompt, world: {
        # Create new agent with fresh context
        subagent_ctx = Context([system_prompt, Entity(prompt)])

        # Run subagent loop until completion
        result_ctx, world' = agent_loop(prompt, world)

        # Return subagent's result as entity
        return Entity(
            type="subagent_result",
            content=extract_result(result_ctx)
        ), world'
    }
)

Key Insight: Subagents are just recursive invocations of the agent loop. The result is returned as an entity to the parent agent.

Example Flow:

Parent Agent:
  User: "Research React hooks and write a summary"

  Turn 1:
    action: spawn_subagent("Research React hooks from documentation")

    Subagent Loop:
      Turn 1: search("React hooks documentation")
      Turn 2: read(url)
      Turn 3: summarize(content)
      Turn 4: respond(summary)

    entity: {type: "subagent_result", content: "React hooks are..."}

  Turn 2:
    Context: [subagent_result, user_input]
    action: write_file("react-hooks-summary.md", content=subagent_result)

7.4 Pattern: RAG (Retrieval-Augmented Generation)

Description: Agent retrieves relevant documents before generating responses.

Implementation:

# RAG is just a special load strategy
def rag_load(ctx, entity, entities):
    # Extract query from latest entity (user input or reasoning)
    query = extract_query(entity)

    # Search knowledge base (world operation)
    relevant_docs = semantic_search(world.knowledge_base, query, top_k=5)

    # Convert docs to entities
    doc_entities = [Entity(doc, type="retrieved_doc") for doc in relevant_docs]

    # Standard load with doc entities included
    return load(ctx, entity, entities + doc_entities)

Key Insight: RAG is just a sophisticated entity discovery mechanism. Retrieved documents are entities loaded into context.

7.5 Pattern: ReAct (Reasoning + Acting)

Description: Agent alternates between reasoning and tool use.

Implementation:

# ReAct is the default agent loop!
# The loop naturally alternates:

Turn 1:
  LLM: reasoning → "Need to check database status"
  Action: execute(check_db_status)

Turn 2:
  LLM: reasoning → "Database is down, need to restart"
  Action: execute(restart_db)

Turn 3:
  LLM: reasoning → "Restart successful, task complete"
  Action: respond("Done!")

Key Insight: ReAct emerges naturally from the agent loop structure. No special implementation needed.

7.6 Pattern: Reflection

Description: Agent reviews and critiques its own work.

Implementation:

# Reflection as a tool that spawns a critic subagent
ReflectionTool = Tool(
    name="reflect",
    description="Review your work for errors and improvements",
    execute=lambda work, world: {
        critique_prompt = f"""
        Review this work: {work}

        Identify:
        1. Errors or bugs
        2. Missed requirements
        3. Potential improvements
        """

        # Spawn critic agent with different system prompt
        critic_ctx = Context([critic_system_prompt, Entity(critique_prompt)])
        result_ctx, world' = agent_loop(critique_prompt, world)

        return Entity(type="reflection", content=extract_result(result_ctx)), world'
    }
)

Usage:

Agent:
  Turn 1: write_code(feature)
  Turn 2: reflect(code)
  Turn 3: revise(code, based_on=reflection)

Key Insight: Reflection is subagent spawning with a specialized critic prompt.

7.7 Pattern: Multi-Agent Collaboration

Description: Multiple agents work in parallel on different aspects of a task.

Implementation:

def parallel_agents(task, world):
    # Decompose task
    subtasks = decompose(task)

    # Spawn agent for each subtask
    results = []
    for subtask in subtasks:
        # Each agent runs independently
        result_ctx, world = agent_loop(subtask, world)
        results.append(extract_result(result_ctx))

    # Coordinator agent synthesizes results
    synthesis_prompt = f"Combine these results: {results}"
    final_ctx, world = agent_loop(synthesis_prompt, world)

    return final_ctx, world

Key Insight: Multi-agent systems are orchestrated by spawning multiple independent agent loops and synthesizing their results.

8. Advanced Topics

8.1 Dynamic Tool Loading

Problem: Loading descriptions of 100+ tools wastes context on irrelevant tools.

Solution: Treat tool discovery as a two-phase load.

Implementation:

# Phase 1: Load tool categories only
tool_categories = [
    Entity("File Operations: read, write, delete, ..."),
    Entity("Network Operations: fetch, post, websocket, ..."),
    Entity("Database Operations: query, insert, update, ..."),
]

ctx = load(ctx, user_input, tool_categories)
reasoning, action = llm(ctx)  # LLM might say "I need file operations"

# Phase 2: Load full tool descriptions only for selected category
if "file" in reasoning.lower():
    file_tools = [Entity(read_tool), Entity(write_tool), ...]
    ctx = load(ctx, Entity(reasoning), file_tools)

Result: Context usage reduced from O(all_tools) to O(relevant_tools).

8.2 Entity Discovery Mechanisms

Entities can specify how they should be discovered:

Entity.metadata = {
    "discovery": {
        "keywords": ["git", "commit", "version control"],  # Keyword match
        "semantic": "Create version control commits",      # Semantic search
        "dependencies": ["read_file", "write_file"],       # Linked entities
        "context_requirements": ["user_in_git_repo"],      # Conditional
    }
}

Use case: GitCommitSkill specifies it should be loaded when:

User mentions "commit" or "git" (keyword)
Current directory is a git repo (context requirement)
If loaded, also load file reading tools (dependencies)

8.3 Tool Data Handling Strategies

Problem: Tool returns 10MB JSON response. Loading fully into context is wasteful.

Strategy 1: Digest on Return

entity, world = execute(action)

# Immediate digest
if entity.size > 10KB:
    entity.content_full = entity.content
    entity.content = llm_summarize(entity.content, max_tokens=500)
    entity.verbosity = "digest"

    # Store full content in world for re-access if needed
    world.store(entity.id, entity.content_full)

Strategy 2: Streaming / Pagination

# Don't load entire result
entity = Entity(
    type="tool_result",
    content="Large file detected. Use read_file(offset=N, limit=M) to page through.",
    metadata={"file_size": "10MB", "total_lines": 50000}
)

Strategy 3: Structured Filtering

# Tool returns structured data with filtering instructions
entity = Entity(
    type="tool_result",
    content={"users": [...]},  # 1000 users
    filter_instructions="Use filter_tool_result(key='users', condition='age > 30') to refine"
)

8.4 Context Compression Strategies

The load function can employ LLM-based compression:

Summarization Compression:

# When context is 80% full
old_messages = ctx.messages[:-10]  # All but last 10
summary = llm_summarize(old_messages)
ctx.messages = [summary] + ctx.messages[-10:]

Semantic Deduplication:

# Remove redundant information
if semantic_similarity(new_entity, existing_entity) > 0.9:
    # Information already in context
    omit(new_entity)

Importance-Based Eviction:

# Score each entity by relevance to current task
scores = [score_relevance(e, current_task) for e in ctx.entities]

# Remove lowest-scored entities when context is full
if ctx.is_full():
    ctx.entities = [e for e, s in sorted(zip(ctx.entities, scores), key=lambda x: -x[1])][:max_entities]

8.5 JIT (Just-In-Time) Context Loading

Concept: Tool results can include instructions for processing their data.

Example:

# Tool execution
entity = execute(search_codebase("authentication"))

# Entity includes loading instructions
entity.content = {
    "results": [
        {"file": "auth.py", "line": 45, "snippet": "..."},
        {"file": "login.py", "line": 12, "snippet": "..."},
        # ... 50 more results
    ],
    "loading_instructions": {
        "default_verbosity": "summary",  # Show only file names + line counts
        "expand_on_request": True,       # Allow LLM to request full snippets
        "expansion_tool": "expand_search_result(index=N)"
    }
}

# Initial load: summary only
load(entity, verbosity="summary")
# Context: "Found authentication code in 52 files. Use expand_search_result(index=N) for details."

# LLM can then selectively expand:
action = expand_search_result(index=0)
# Returns full snippet from auth.py

Benefit: LLM gets overview first, then drills down only where needed.

8.6 Multi-Level Tool Descriptions

Tools can define descriptions at multiple granularities:

Tool.descriptions = {
    "title": "read_file",

    "one_liner": "Read file contents",

    "summary": """
        read_file(path) → string
        Reads and returns file contents from disk.
    """,

    "detailed": """
        read_file(path, offset=0, limit=None) → string

        Reads file contents from the filesystem.

        Parameters:
        - path: Absolute path to file
        - offset: Starting line number (0-indexed)
        - limit: Maximum number of lines to read

        Returns: File contents as string

        Errors: FileNotFoundError, PermissionError

        Example:
            content = read_file("/home/user/config.json")
    """,
}

Load Strategy:

# When context is spacious: load detailed
# When context is tight: load summary
# When very tight: load one_liner only
# When nearly full: load title only (just function name)

verbosity = choose_verbosity_level(ctx.available_space)
tool_entity.content = tool.descriptions[verbosity]

9. Integration with Existing Systems

9.1 Mapping to Real Agent Frameworks

LangChain:

# LangChain concepts → Entity Calculus
Agent = LLM + Harness
Tools = List[Entity(tool_description)] + execute handlers
Memory = Entity(conversation_buffer, type="memory", loading="preloaded")
Chains = Predefined entity sequences
Callbacks = Instrumentation hooks in harness.load and harness.execute

AutoGen:

# AutoGen concepts → Entity Calculus
ConversableAgent = Agent (LLM + Harness)
UserProxyAgent = Agent with (no LLM, execute only harness)
GroupChat = Multi-agent with shared entity pool
Human-in-loop = User input injected as entity during loop

Cursor / Copilot:

# IDE agent concepts → Entity Calculus
Codebase Context = List[Entity] from semantic search over code
Active File = Entity(current_file, loading="preloaded", verbosity="full")
Related Files = List[Entity(file, loading="dynamic", verbosity="summary")]
LSP Information = Entity(type_info + references, loading="on-demand")

9.2 RAG Systems

Traditional RAG:

query = user_input
docs = vector_db.search(query)
context = [system_prompt, docs, query]
response = llm(context)

Entity Calculus RAG:

# Documents are just entities!
entities = [
    Entity(system_prompt, loading="preloaded"),
    Entity(user_input, loading="preloaded"),
    *[Entity(doc, loading="dynamic", discovered_by="semantic_search")
      for doc in vector_db.search(user_input)]
]

# Standard agent loop
ctx = harness.load(Context(), entities)
reasoning, action = llm(ctx)

Key Insight: RAG is entity discovery via semantic search.

10. Future Directions & Open Questions

10.1 Entity Discovery as a Graph

Idea: Entities can link to related entities, forming a graph.

Entity(GitCommitSkill).links = [
    Link(Entity(ReadFileTool), relation="requires"),
    Link(Entity(WriteFileTool), relation="requires"),
    Link(Entity(GitStatusTool), relation="uses"),
    Link(Entity(PRCreationSkill), relation="related_to"),
]

Use Case: When GitCommitSkill is loaded, harness can automatically load linked tools.

Question: How to prevent exponential blow-up of linked entities?

10.2 Entity-Provided Processing Instructions

Idea: Entities specify how they should be processed after use.

Entity(tool_result).processing_hints = {
    "after_llm_reads": "compress_to_digest",
    "after_N_turns": "omit_if_not_referenced",
    "if_context_full": "move_to_world_storage"
}

Benefit: Declarative context management instead of imperative harness logic.

Question: How to balance entity autonomy with global context optimization?

10.3 Learned Context Management

Idea: Use ML to learn optimal loading strategies.

# Train a model to predict:
# - Which entities to load given task
# - What verbosity level to use
# - When to compress/omit entities

load_policy = train(
    inputs=[task_embedding, available_entities, context_state],
    outputs=[entities_to_load, verbosity_levels],
    objective=maximize(task_success_rate) - penalize(context_usage)
)

Question: How to collect training data? What are the right features?

10.4 Hierarchical Entities

Idea: Entities can contain sub-entities.

Entity(Codebase) = {
    "type": "collection",
    "children": [
        Entity(Module1),
        Entity(Module2),
        ...
    ]
}

# Load strategy:
# - Initially load: Entity(Codebase, verbosity="summary")
#   → "Codebase contains 50 modules in 3 categories"
# - On demand: Entity(Module1, verbosity="full")

Use Case: Representing complex structured knowledge (codebases, documentation sites, databases).

10.5 Entity Lifecycle Hooks

Idea: Entities can define callbacks for lifecycle events.

Entity.hooks = {
    "on_load": lambda ctx: validate_dependencies(ctx),
    "on_compress": lambda content: custom_summarize(content),
    "on_evict": lambda: persist_to_world(),
    "on_access": lambda: log_usage_analytics(),
}

Benefit: Entities become active components, not passive data.

10.6 Cross-Agent Entity Sharing

Idea: Multiple agents share a common entity pool.

# Shared world with entity store
world.entity_store = {
    "current_task": Entity(...),
    "research_results": Entity(...),
    "code_changes": Entity(...),
}

# Agent A updates entity
agent_a.execute(update_entity("research_results"))

# Agent B reads updated entity
ctx_b = load(ctx_b, world.entity_store["research_results"])

Use Case: Multi-agent collaboration with shared knowledge.

Question: How to handle conflicts? Consistency guarantees?

10.7 Speculative Entity Loading

Idea: Preemptively load entities the LLM might need.

# Predict future entity needs
predicted_entities = predict_next_entities(
    ctx.current_state,
    llm.recent_actions
)

# Load them in background (if context space available)
for e in predicted_entities:
    if ctx.has_space():
        ctx = load(ctx, e, verbosity="summary")

Benefit: Reduced latency for multi-turn interactions.

Question: How to predict accurately without wasting context?

10.8 Differential Context Updates

Idea: Instead of reloading full context, send only diffs.

# Current approach: send full context every turn
llm(full_context) → action

# Differential approach:
llm.update(
    add=[new_entity],
    remove=[old_entity_id],
    modify=[entity_id, new_content]
)

Benefit: Reduced token usage, faster inference.

Challenge: Requires stateful LLM API (not common yet).

10.9 Entity Versioning

Idea: Track entity changes over time.

Entity.versions = [
    (timestamp=0, content="Initial user query"),
    (timestamp=5, content="Elaborated with clarifications"),
    (timestamp=10, content="Further refined based on context"),
]

# Load appropriate version based on temporal context
ctx = load(ctx, entity.version_at(time=5))

Use Case: Understanding how agent's understanding evolved. Debugging. Time-travel debugging.

10.10 Meta-Entities

Idea: Entities that describe other entities.

MetaEntity(
    target=Entity(large_tool_result),
    metadata={
        "summary": "Database query returned 10K rows",
        "schema": {columns: [...], types: [...]},
        "relevance_to_task": 0.85,
        "recommended_verbosity": "digest",
    }
)

Benefit: Richer metadata for smarter loading decisions.

11. Conclusion

The Entity Calculus provides a unified lens for understanding AI agents:

Everything is an entity: Skills, tools, memory, data—all flow through the same abstraction.
Harness manages entity flow: The load and execute functions orchestrate entity movement between context and world.
Context is the bottleneck: All optimizations revolve around the limited context window.
Patterns emerge naturally: Common agent patterns (ReAct, RAG, multi-agent) are special cases of entity flow.
Composability: Because everything is an entity, components compose cleanly.

Key Insights

Agent = LLM + Harness cleanly separates reasoning (LLM) from orchestration (harness).
Entity abstraction unifies disparate concepts under one model.
Load/Execute duality captures the full agent loop: load entities into context, execute actions in world.
Multi-agent systems are recursive applications of the same calculus.

Practical Value

For researchers, this framework provides:

Formal vocabulary for discussing agent architectures
Basis for systematic analysis of agent behaviors
Foundation for developing new context management techniques

For engineers, this framework provides:

Clear mental model for designing agents
Reusable patterns for common agent tasks
Principled approach to context optimization

Next Steps

We invite the community to:

Implement reference harnesses following this calculus
Develop benchmarks for entity loading strategies
Explore the open questions outlined in Section 10
Extend the calculus to new domains (e.g., multimodal agents, embodied agents)

References

Appendix: Notation Reference

Symbol	Meaning
`LLM: Context → (Reasoning, Actions)`	LLM as pure function
`Agent = LLM + Harness`	Agent decomposition
`load: (Context, Entity, List[Entity]) → Context'`	Harness load function
`execute: (Action, World) → (Entity, World')`	Harness execute function
`Entity`	Unit of information loadable into context
`Context`	LLM's directly accessible information
`World`	External state outside context
`verbosity ∈ {full, summary, digest, reference}`	Entity loading granularity
`loading ∈ {preloaded, dynamic}`	Entity loading strategy

Document Version: 1.0
Last Updated: January 15, 2026

Koka.py: Type-Checked Dependency Injection and Error Handling in Python

Herrington Darkholme — Mon, 15 Dec 2025 01:56:04 +0000

Exploring algebraic effects inspired by Effect-TS, ZIO, and the Koka language

The Problem: Python's Hidden Dependencies and Exceptions

Every developer encounters two questions when reading unfamiliar code:

"What does this function need to work?"
"What can go wrong when I call this?"

Consider a typical Python function:

def get_user_profile(user_id: str) -> UserProfile:
    token = request.headers.get("Authorization")
    user = auth_service.verify(token)

    cached = cache.get(f"user:{user_id}")
    if cached:
        return cached

    return database.find_user(user_id)

To answer our two questions, you must read the entire implementation. Where does auth_service come from? What happens if verify() fails? Can find_user() return None? The type signature (str) -> UserProfile tells you almost nothing.

This problem compounds in real applications with layered architectures:

handle_request() 
 → get_user_profile() 
  → authenticate() 
   → check_cache() 
    → query_db()

Each layer can have its own dependencies and failure modes. Traditional Python keeps dependencies implicit and errors unchecked. The result: runtime surprises, missing error handling, and unclear contracts.

What if the type signature told you everything?

def get_user_profile(user_id: str) -> Eff[
    Dep[AuthService] | Dep[Database] | Dep[CacheService] | AuthError | NotFoundError,
    UserProfile
]:
    ...

Now you know: this function needs AuthService, CacheService and Database, might fail with AuthError or NotFoundError, and returns UserProfile. All without reading a single line of implementation.

This is what the koka library enables.

What Are Algebraic Effects? (A Practical Take)

Skip the academic theory. Here's the practical framing:

Effects are declared capabilities—what a function needs to run and how it can fail. Think of it as making the implicit explicit, and letting the type checker verify it.

The koka library provides two key effects:

Dep[T] — "I need an instance of type T to run"
Err[E] — "I might fail with error E"

The key insight: effects compose automatically. If function A needs Dep[Database] and function B needs Dep[Cache], and function C calls both A and B, then C's type automatically includes Dep[Database] | Dep[Cache]. The type checker infers this—no manual annotation needed.

The Inspiration Chain

This pattern didn't emerge from nowhere. It follows a lineage of innovation:

Academic research on algebraic effects and handlers (Plotkin, Pretnar, et al.)
Koka language — a research language that pioneered practical algebraic effects
ZIO (Scala) — brought effect systems to mainstream functional programming at zio.dev
Effect-TS (TypeScript) — made effects accessible to the JavaScript ecosystem
koka (Python) — brings these ideas to Python, leveraging Python 3.13's type system

This library is an exploration of whether Python's type system and generators can express the same patterns that have proven valuable in other ecosystems.

Real-World Example: User Lookup Service

Let's build a realistic scenario with multiple failure modes that map to different HTTP responses.

Layer 1: Authentication

class AuthError(Exception):
    """Invalid or missing authentication. Maps to HTTP 401 Unauthorized."""
    pass

class AuthService:
    def verify(self, token: str) -> User | None:
        ...

def authenticate(token: str) -> Eff[Dep[AuthService] | AuthError, User]:
    auth: AuthService = yield from Dep(AuthService)
    user: User | None = auth.verify(token)
    if user is None:
        return (yield from Err(AuthError("Invalid token")))
    return user

The type signature Eff[Dep[AuthService] | AuthError, User] tells you:

Needs: AuthService
Can fail with: AuthError
Returns: User

Layer 2: Cache Lookup

class CacheMiss(Exception):
    """Internal signal—don't expose to HTTP clients."""
    pass

class CacheService:
    def get(self, key: str) -> UserProfile | None:
        ...

def get_from_cache(user_id: str) -> Eff[Dep[CacheService] | CacheMiss, UserProfile]:
    cache: CacheService = yield from Dep(CacheService)
    data: UserProfile | None = cache.get(f"user:{user_id}")
    if data is None:
        return (yield from Err(CacheMiss()))
    return data

Layer 3: Database Lookup

class NotFoundError(Exception):
    """User doesn't exist. Maps to HTTP 404 Not Found."""
    pass

class Database:
    def find_user(self, user_id: str) -> UserProfile | None:
        ...

def get_from_db(user_id: str) -> Eff[Dep[Database] | NotFoundError, UserProfile]:
    db: Database = yield from Dep(Database)
    data: UserProfile | None = db.find_user(user_id)
    if data is None:
        return (yield from Err(NotFoundError(f"User {user_id} not found")))
    return data

Layer 4: Composed Handler

Now we compose these layers into a single handler:

def get_user_profile(
    token: str,
    user_id: str
) -> Eff[
    Dep[AuthService] | Dep[CacheService] | Dep[Database] | AuthError | NotFoundError,
    UserProfile
]:
    # First authenticate (can fail with AuthError → 401)
    user: User = yield from authenticate(token)

    # Try cache first (handle CacheMiss internally)
    cache: CacheService = yield from Dep(CacheService)
    cached: UserProfile | None = cache.get(f"user:{user_id}")
    if cached is not None:
        return cached

    # Fall back to database (can fail with NotFoundError → 404)
    return (yield from get_from_db(user_id))

The type signature reveals everything:

Dependencies: AuthService, CacheService, Database
Possible errors: AuthError (→ 401), NotFoundError (→ 404)
Return type: UserProfile

Note that CacheMiss doesn't appear in the final signature—we handled it internally by falling back to the database.

Running the Effect

result: UserProfile | AuthError | NotFoundError = (
    Koka()
    .provide(AuthService())
    .provide(CacheService())
    .provide(Database())
    .run(get_user_profile("token-123", "user-456"))
)

# Pattern match to HTTP responses
match result:
    case AuthError() as e:
        return HttpResponse(401, f"Unauthorized: {e}")
    case NotFoundError() as e:
        return HttpResponse(404, f"Not Found: {e}")
    case UserProfile() as profile:
        return HttpResponse(200, profile.to_json())

The Koka runtime ensures all dependencies are provided. If you forget to .provide(Database()), you get a type error—not a runtime AttributeError.

How `yield from` Achieves This

The magic happens through Python's generator protocol. Here's how it works.

The `Eff` Type

type Eff[K, R] = Generator[K, Never, R]

K — the effects yielded (union of Dep[T] types and exception types)
R — the return type

How `Dep[T]` Works

class Dep[T]:
    def __init__(self, tpe: type[T]) -> None:
        self.tpe = tpe

    def __iter__(self) -> Generator[Self, T, T]:
        return (yield self)  # Yield the request, receive the instance

When you write db = yield from Dep(Database):

The generator yields Dep(Database) — a request for a Database instance
The runtime receives this request and looks up the handler
The runtime sends the Database instance back into the generator
db receives the Database instance

The type checker sees:

You're yielding Dep[Database] (adds to effect set K)
You're receiving Database (the return type)

How `Err[E]` Works

class Err[E: Exception]:
    def __init__(self, err: E) -> None:
        self.error = err

    def __iter__(self) -> Generator[E, Never, Never]:
        yield self.error  # Yield the error, never resume
        raise RuntimeError("Unreachable")  # Type: Never

When you write return (yield from Err(NotFoundError(...))):

The generator yields the NotFoundError exception
The runtime receives it and returns it as the final result
The generator never resumes (hence Never return type)

The type checker sees:

You're yielding NotFoundError (adds to effect set K)
The expression type is Never (computation doesn't continue)

Effect Composition

When you yield from authenticate(token) inside get_user_profile:

authenticate has effects Dep[AuthService] | AuthError
These get added to get_user_profile's effect set
The type checker automatically computes the union:

  Dep[AuthService] | AuthError | Dep[CacheService] | Dep[Database] | NotFoundError

This is why you don't need to manually declare the effect types—the type checker infers them from usage.

The Alternative: Manual Return Types

Can we achieve the same type safety without generators? Let's try using explicit return types.

Attempt: Pass Dependencies, Return Union Types

def authenticate(
    auth: AuthService,
    token: str
) -> User | AuthError:
    user: User | None = auth.verify(token)
    if user is None:
        return AuthError("Invalid token")
    return user


def get_from_db(
    db: Database,
    user_id: str
) -> UserProfile | NotFoundError:
    data: UserProfile | None = db.find_user(user_id)
    if data is None:
        return NotFoundError(f"User {user_id} not found")
    return data


def get_user_profile(
    auth: AuthService,
    cache: CacheService,
    db: Database,
    token: str,
    user_id: str
) -> UserProfile | AuthError | NotFoundError:
    # Check auth
    auth_result: User | AuthError = authenticate(auth, token)
    if isinstance(auth_result, AuthError):
        return auth_result
    user: User = auth_result

    # Try cache
    cached: UserProfile | None = cache.get(f"user:{user_id}")
    if cached is not None:
        return cached

    # Try database
    db_result: UserProfile | NotFoundError = get_from_db(db, user_id)
    if isinstance(db_result, NotFoundError):
        return db_result

    return db_result

The Problems

1. Dependency Threading

Every function must explicitly accept and pass through all dependencies. get_user_profile takes 5 parameters—3 of which are just dependency plumbing. In deep call stacks, this becomes unmanageable:

def handle_request(
    auth: AuthService,
    cache: CacheService,
    db: Database,
    email: EmailService,
    logger: Logger,
    metrics: MetricsService,
    token: str,
    user_id: str
) -> ...:
    # Every layer needs all these parameters
    ...

2. Manual Error Type Union

You must manually declare -> UserProfile | AuthError | NotFoundError. Forget one, and callers get type errors—or worse, the type checker misses a case. As you add more error types, the union grows unwieldy:

def complex_operation(...) -> Result | ErrorA | ErrorB | ErrorC | ErrorD | ErrorE:
    ...

3. Nested isinstance Checks Destroy Readability

result1 = step1(...)
if isinstance(result1, Error1):
    return result1

result2 = step2(result1, ...)
if isinstance(result2, Error2):
    return result2

result3 = step3(result2, ...)
if isinstance(result3, Error3):
    return result3

# This continues for EVERY call that can fail

Linear code becomes a staircase of error checks, obscuring the happy path.

4. No Automatic Inference

The type checker can't infer what dependencies or errors are needed—you must declare everything manually. Add a new error case deep in the call stack? Update every function signature up to the top.

Comparison Table

Aspect	`yield from` (koka)	Return types
Dependencies	Inferred from usage	Explicit parameters
Error types	Inferred from `Err()` calls	Manual union annotation
Control flow	Linear, readable	Nested `isinstance` checks
Composition	Automatic	Manual threading
Adding new dependency	Just use it	Update all callers
Adding new error type	Just yield it	Update all signatures

The `yield from` Version (For Contrast)

def get_user_profile(
    token: str,
    user_id: str
) -> Eff[
    Dep[AuthService] | Dep[CacheService] | Dep[Database] | AuthError | NotFoundError,
    UserProfile
]:
    user: User = yield from authenticate(token)

    cache: CacheService = yield from Dep(CacheService)
    cached: UserProfile | None = cache.get(f"user:{user_id}")
    if cached is not None:
        return cached

    return (yield from get_from_db(user_id))

Two parameters. Linear flow. Types inferred automatically.

Why Not `async/await`?

A natural question: Python already has async/await for suspending and resuming functions. Why not use that?

Different problem domains. async/await solves I/O scheduling—letting the event loop run other tasks while waiting for network or disk. It doesn't track "what capabilities a function needs."

async def get_user(user_id: str) -> User:
    ...  # What dependencies? What errors? The signature doesn't say.

There's no mechanism to declare "this async function needs a Database" in a way the type checker can verify.

Function coloring. Async functions can only be called from async contexts. This "colors" your entire codebase—one async function forces async up the call stack. Generators don't have this problem; they're just values you can compose and run synchronously.

No custom interpretation. With async/await, the event loop is the only interpreter. With generators, we can write custom runtimes that handle effects differently—inject mocks for testing, swap implementations for different environments, etc.

An Experiment Worth Exploring

Let's be clear: koka is experimental. It's a proof of concept exploring whether Python can express the effect patterns that have proven valuable in TypeScript (Effect-TS), Scala (ZIO), and research languages (Koka).

What makes this possible now?

Python 3.13 introduced new type syntax (PEP 695) that makes generic types more ergonomic. Combined with mature type checkers like pyright, we can finally express complex type relationships that would have been impossibly verbose before.

What's the value for Python developers?

This library demonstrates that type-checked effect systems are possible in Python—today, with zero runtime dependencies beyond standard generators. It shows a path toward code where:

Dependencies are explicit and verified at type-check time
Errors are tracked and exhaustively handled
Function signatures serve as reliable documentation

This invites a question for the Python community: Should we have better support for this pattern? Could future Python versions make effect tracking even more ergonomic?

Try it yourself:

pip install koka

The goal: answer "what does this function need?" and "what can go wrong?" at a glance. Let your type checker become your documentation.

Beyond the Platform: Is Vercel Designing the Future of Programming Languages?

Herrington Darkholme — Wed, 29 Oct 2025 04:54:43 +0000

Vercel has recently rolled out features that do more than just enhance its platform—they challenge the very semantics of JavaScript and offer a glimpse into a new era of programming. While these changes have sparked debate, they hint at a broader, more ambitious vision.

Vercel is championing the idea that the next generation of programming languages should natively manage the complexities of modern applications, including heterogeneous runtimes, transparent networks, multi-layer caching, and task durability.

This article explores how programming languages might be evolving to manage not just logic, but the entire lifecycle of data and computation in distributed systems. This evolution is being quietly prototyped through three core language concepts: serializable closures, algebraic effects, and incremental computation.

Vercel's New Primitives for a Distributed World

To understand this future, we must first look at the problems Vercel is solving today. Modern web applications are becoming more complex, featuring:

Multiple Runtimes: Code executes on the client (browser), the server (Node.js), and the edge (WebAssembly).
Dispersed Data: State lives in memory, on CDNs, in databases, and across file storage.

To tame this complexity, Vercel, together with the React team, have introduced powerful new features that feel less like library additions and more like new language constructs.

Server Actions: Unifying Client and Server Logic

Server Actions allow client-side components to directly call asynchronous functions that execute on the server, effectively erasing the boundary between client and server code.

// server.ts
"use server";
export async function createNote() {
  await db.notes.create();
}

// client.ts
"use client";
// The import is transformed by the compiler into a reference:
// {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNote'}
import {createNote} from './server';

function EmptyNote() {
  return (
    <button onClick={() => createNote()}>Create Note</button>
  );
}

Without Server Actions, this would require manually setting up API endpoints, writing fetch requests, and handling data serialization and deserialization. Server Actions abstract all of this away, making remote procedure calls (RPCs) feel like simple function calls.

The 'use cache' Directive: Language-Level Caching

The 'use cache' directive is a powerful tool for memoizing functions and caching their results. The cache key is automatically generated from the function's arguments and its closed-over values—the variables from its surrounding scope that it "remembers."

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`);
    return data;
  }
  return //...
}

This is a true language-level feature. Because it needs to inspect the function's closure, it cannot be implemented as a simple library API without forcing developers to manually declare all dependencies.

The 'use workflow' Directive: Durable, Resumable Functions

Making asynchronous tasks reliable typically requires a complex stack of message queues, retry logic, and persistence layers. The 'use workflow' directive aims to make durability a native language concept.

A workflow is a function that can maintain its execution state across restarts, failures, or long pauses. It can resume exactly where it left off, whether it was paused for seconds or months.

export async function aiAgentWorkflow(query: string) {
  "use workflow";
  const response = await generateResponse(query);
  const facts = await researchFacts(response);
  const refined = await refineWithFacts(response, facts);
  return { response: refined, sources: facts };
}

Key Characteristics of Workflows:

Durable: They survive deployments and crashes through deterministic replays from an event log.

Resumable: Execution can be paused and resumed at any await point.

Deterministic: They run in a sandboxed environment where non-deterministic APIs (like Math.random or Date.now) are controlled to ensure replayability.

By baking durability into the language with a simple directive, 'use workflow' abstracts away immense infrastructural complexity.

The Historical Arc of Programming Languages

You may feel uneasy about these changes to JavaScript. After all, they alter the language's semantics in significant ways.
However, if we look at the history of programming languages, we see a consistent pattern of evolution aimed at managing increasing complexity.

Programming languages have always evolved to manage new layers of abstraction and complexity:

Assembly managed raw CPU instructions.
C abstracted away registers and control flow.
Java automated memory management.
Go simplified concurrency for multi-core processors.

The next logical step in this evolution is to manage the complexities of data management. The challenge is no longer just managing memory or threads, but managing where computation happens, how data moves, and how to ensure that access is fast, persistent, and reliable.

Currently, these are problems solved by frameworks, libraries, and external systems. A developer needs a deep understanding of serialization, RPCs, caching strategies, and message queues. Vercel's new features suggest a future where these are concerns of the language itself.

The Language Features Powering This Vision

Vercel's new directives have been controversial precisely because they alter JavaScript's semantics. Instead, if we see from another perspective, they can be built on powerful concepts from computer science that could form the foundation of a new kind of programming language.

Serializable Closures

A closure is a function that "remembers" the environment in which it was created. A serializable closure is one that can be packaged up—its code and its remembered environment—and sent across a network, stored in a database, or executed at a later time. This effectively allows us to move computation, not just data, across system boundaries.

function serlializeClosure(fn) {
  const { closureData, fnCode } = extractClosedOverVariables(fn);
  return {
    code: fnCode,
    closure: closureData
  };
}

Server Actions are a prime example. The createNote function is serialized, sent to the client as a reference, and when invoked, its execution is triggered back on the server.

// Simplified Concept:
// 1. On the server, the function and its closure are captured.
const { closure, code } = serializeClosure(createNote);
const fnId = storeCodeOnServer(code);

// 2. A reference is sent to the client.
sendToClient({ fnId, closure });

// 3. The client uses the reference to invoke the function on the server.
invokeServerFunction({ fnId, closure, fnArgs: [...] });

'use cache' relies on serialization to create a unique cache key. The function's code, its closed-over values, and its arguments are hashed together.

function getCacheKey(fn, args) {
  const { closure, code } = serializeClosure(createNote);
  return hash(fnCode, closureData, args);
}

Workflows can be seen as serializable closures that are paused at each await point. The state of the function and its continuation (the "rest" of the function) is serialized and persisted, ready to be resumed later.

For example, the aiAgentWorkflow function can be visualized as a series of serialized closures at each step:

function aiAgentWorkflow(query: string) {
  return generateResponse(query, (response) => {
    // serialize closure 1
    researchFacts(response, (facts) => {
      // serialize closure 2
      refineWithFacts(response, facts, (refined) => {
        // serialize closure 3
        return { response: refined, sources: facts };
      });
    });
  })
}

Algebraic Effects

Serializable closures are powerful, but they introduce a critical challenge: how do you safely execute a piece of code in a different environment? A function designed to run on the server can't access a database if it's moved to a browser.

This is where algebraic effects come in. Algebraic effects are a programming language feature that separates what a function does (its side effects, like accessing a database or generating a random number) from how those effects are implemented.

An "effect" is performed, and an "effect handler" somewhere up the call stack decides how to interpret it.

The 'use workflow' environment is a perfect example. APIs like Math.random and Date.now must behave deterministically. An effect handler could intercept a call to Date.now and, instead of returning the system time, return a timestamp from the workflow's event log to ensure replayability.

Another example in a hypothetical language with first-class effects, you could define different handlers for client and server contexts:

// Define an effect for database access
function dbAccessEffect(userQuery) {
  const user =
    yield* db.fetchEffect<User, Error, ServerContext>(userQuery);
  return user;
}

// On the server, the handler provides the database context
const user = serverHandler.runEffect(dbAccessEffect, query); // OK

// On the client, the handler would throw an error, as no db is available
// clientHandler.runEffect(dbAccessEffect, query); // Throws Error

This provides a secure and reliable way to control what resources a movable closure can access.

The idea is not something new to the JavaScript world. Library like Effect and languages like Koka have explored algebraic effects for years. But using effect to manage different execution environments and resource access is a novel and powerful application of the concept.

Incremental Computation

In a distributed system, caching isn't just an optimization—it's essential for performance. Incremental computation is the principle of only recomputing outputs that are affected by a change in data, rather than recomputing everything from scratch.

This concept is already widespread:

React's Virtual DOM diffing is a form of incremental computation.
Memoization and directives like 'use cache' are explicit forms of it.
Build systems like Turbopack and Bazel use it to avoid re-building unchanged code.

By making incremental computation a first-class language concept, a future language could automatically manage caching and data dependencies across different rendering strategies (CSR, SSR, SSG, ISR), build systems, and data layers, dramatically improving efficiency.

In fact, "use cache" can be seen as a simple form of incremental computation. A more advanced system could track dependencies at a finer granularity, allowing for partial recomputation when only some data changes. This idea has been explored in JavaScript world, exemplified by projects like skiplabs and Skip langs.

The Dawn of a "Vercel Lang"?

Vercel is not just building a platform; it is embedding a powerful programming model directly into the developer experience. By introducing language-level constructs for distributed systems, they are pushing the boundaries of what developers can build and how easily they can build it.

Is this a good thing? The debate is ongoing, but the direction is clear. This paradigm could be pushed even further. Imagine a language where:

Error monitoring is managed by the platform. A function could declare its potential errors, and the language and platform could automatically provide monitoring and alerting.
Data privacy and security are compiler-enforced. By tracking data flow through an effect system, the language could enforce access controls and prevent sensitive data leaks.
Observability is built-in. An effect system could manage access to resources like databases, providing deep insights into performance without manual instrumentation.

The next-era programming language itself understands and manages the distributed nature of modern applications, freeing developers to focus on logic, not infrastructure.

Trying Out Biome v2's Type Inference and Knowing Its Limits

Herrington Darkholme — Wed, 25 Jun 2025 03:53:38 +0000

This article is the English translation of the article "Biome v2の型推論を試して限界を知る" from Zenn. Thank the original author Uhyo for their write-up!

Hello everyone. The other day, Biome v2 was released and became a hot topic. One of the new features in Biome v2 is type inference.

Until now, type-aware linting for TypeScript code has been provided by TypeScript-ESLint. This has the disadvantage of being heavy because it uses the actual TypeScript compiler to obtain type information. While TypeScript itself is working on performance improvements through porting to Go and other measures, Biome has taken a different approach to this problem. That is, to perform type inference independently without relying on the official TypeScript compiler.

However, the TypeScript compiler is an extremely complex system, and it is almost impossible to completely reproduce its type inference results with a separate implementation. Therefore, Biome's type inference also cannot perfectly replicate the behavior of the TypeScript compiler. The Biome v2 release notes state that, using the noFloatingPromises rule as an example, it can detect about 75% of the cases compared to using the actual TypeScript compiler.

Therefore, in this article, I will try out the type inference feature of Biome v2 and examine how well it can infer types compared to the real TypeScript compiler.

Note: This article examines the version at the time of writing (2.0.4). Biome has announced that it will improve type inference in future versions.

Simple Example

This time, I will investigate using the noFloatingPromises rule. This rule detects code where a Promise is not awaited. First, let's look at a simple example.

async function foo() {
  return 3.14;
}

export async function main() {
  foo();
}

In this code, the foo function returns a Promise, but the main function does not await its result. Therefore, a lint error is expected.

Running biome lint on this code produces the following error:

index.ts:6:3 lint/nursery/noFloatingPromises FIXABLE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ A "floating" Promise was found, meaning it is not properly handled and could lead to ignored errors or unexpected behavior.

  5 │ export async function main() {
> 6 │   foo();
    │   ^^^^^^
  7 │ }

ℹ This happens when a Promise is not awaited, lacks a `.catch` or `.then` rejection handler, or is not explicitly ignored using the `void` operator.

ℹ Unsafe fix: Add await operator.

  6 │ ··await·foo();
    │ ++++++

It detects that the return value of foo() is a Promise and points out that await is necessary. Although foo() has no explicit type annotation, Biome infers the function's return value and determines that it is a Promise.

From here, we will gradually make the inference more difficult.

Using `new Promise`

In the example above, because foo was defined as an async function, it was very clear that the return value was a Promise. Next, let's try using new Promise.

function foo() {
  return new Promise<number>((resolve) => {
    setTimeout(() => {
      resolve(3.14);
    });
  });
}

export async function main() {
  foo();
}

In this example, the return value of the foo function is still a Promise. However, it uses new Promise without the async keyword.

Running biome lint on this code did not detect any lint errors.

Unfortunately, in this case, it seems that Biome cannot recognize that the function's return value is a Promise. In this case, since there is no type annotation for the return value of foo, to find the type of foo, it is necessary to look for the return statement inside foo, confirm that its value is new Promise, and then check that the type of this expression is a Promise. However, it seems that Biome cannot perform this kind of type inference.

Explicitly Adding a Type Annotation

Now, let's add a type annotation to the function's return value.

function foo(): Promise<number> {
  return new Promise<number>((resolve) => {
    setTimeout(() => {
      resolve(3.14);
    });
  });
}

export async function main() {
  foo();
}

With this, Biome was able to detect the lint error.

Although I haven't looked at the internal implementation of Biome's type inference, it seems that it does not examine the content of a function to determine its return type. To utilize Biome's type inference, it is important to explicitly state the return type of functions.

Trying Out `Promise`

Now, let's go back to using async functions for clarity and try various things.

async function foo(): Promise<number> {
  return 3.14;
}

export async function main() {
  console.log(foo());
}

When running biome lint on this example, surprisingly, no error was detected. I was personally a bit surprised by this.

However, the official documentation for the noFloatingPromises rule states the following about its behavior:

This rule will report Promise-valued statements that are not treated in one of the following ways:

Calling its .then() method with two arguments

Calling its .catch() method with one argument

awaiting it

returning it

voiding it

Since it refers to "Promise-valued statements", it can be interpreted that when a Promise is used as an expression in something, it is not a target, and the detection is limited to cases where a Promise is left alone, like foo();.

Perhaps for this reason, even when a Promise is assigned to a variable as shown below, no lint error was detected.

async function foo(): Promise<number> {
  return 3.14;
}

export async function main() {
  const p = foo();
  console.log(p);
}

Through an Object

I also tried the case of an object method instead of a function.

const obj = {
  foo: async () => {
    return 3.14;
  },
}

export async function main() {
  obj.foo();
}

In this case, a lint error was detected. It seems that through some inference, it understood that obj.foo is a function that returns a Promise.

By the way, the lint error disappears as shown below (although an error for using any appears instead).

const obj: { foo: any; } = {
  foo: async () => {
    return 3.14;
  },
}

export async function main() {
  obj.foo();
}

From this, it can be seen that it properly infers the "type of obj" and through that, infers the type of the return value of obj.foo.

Trying Difficult Types

Now, let's be mean and try some of TypeScript's difficult types.

Generics

First, here is an example using generics.

function id<T>(x: T): T {
  return x;
}

async function foo(): Promise<number> {
  return 3.14;
}

export async function main() {
  id(foo());
}

In this example, the return value of id(foo()) will be a Promise, but without performing generic type inference, it cannot understand that.

I was most surprised by the result here, but surprisingly, Biome detected a lint error for this example. This means it was able to recognize that the return value of id(foo()) is a Promise. The lint error is correctly detected for id and not foo().

The inference rules for generics in TypeScript are very complex, so I don't think Biome can reproduce all of them, but it seems that in simple cases like this example, it can perform type inference using generics.

Lookup Types

A lookup type is a type with a syntax like T[K].

interface Obj {
  noPromise: number;
  yesPromise: Promise<number>;
}

const obj: Obj = {
  noPromise: 3.14,
  yesPromise: Promise.resolve(3.14),
}

function foo<K extends keyof Obj>(key: K): Obj[K] {
  return obj[key];
}

export async function main() {
  foo('noPromise');
  foo('yesPromise');
}

In this case, the return value of foo('noPromise') is of type number, but the return value of foo('yesPromise') is of type Promise<number>. Can Biome figure this out?

The answer is, unfortunately, no lint error was detected for foo('yesPromise'). It seems that it does not support calculations of lookup types.

By the way, even a simple case like the one below without generics was not possible.

interface Obj {
  noPromise: number;
  yesPromise: Promise<number>;
}

async function foo(): Obj["yesPromise"] {
  return 3.14;
}

export async function main() {
  foo();
}

Mapped Types and Conditional Types

Since lookup types were not possible, I thought the rest would be impossible too, but I tried them anyway. As expected, it was not possible.

// Mapped Type
type Raw = {
  noPromise: number;
  yesPromise: Promise<number>;
}

type Obj = {
  [K in keyof Raw]: () => Raw[K];
}

const obj: Obj = {
  noPromise: () => 42,
  yesPromise: () => Promise.resolve(3.14),
}

export async function main() {
  obj.yesPromise();
}

// Conditional Type
function foo<K extends string | number>(key: K): K extends string ? number : Promise<number> {
  if (typeof key === 'string') {
    return 42 as any;
  } else {
    return Promise.resolve(42) as any;
  }
}

export async function main() {
  foo(123);
}

Union and Intersection Types

Union types are important in practical TypeScript. Let's try a case involving them.

function foo(): number | Promise<number> {
  if (Math.random() > 0.5) {
    return 42;
  }
  return new Promise((resolve) => {
    setTimeout(() => resolve(42), 1000);
  });
}

export async function main() {
  foo(123);
}

In this case, foo(123) may or may not be a Promise.

For this example, Biome detected a lint error. This means it can recognize the possibility of a Promise as part of a union type.

Now, let's also try an intersection type.

function foo(): Promise<number> & { abort: () => void} {
  return {} as any; // omitted
}

export async function main() {
  foo();
}

For this one, no lint error was detected. It seems that it cannot recognize the presence of a Promise as part of an intersection type. However, whether this should be a detection target may be a matter of judgment. Also, since there is no essential difficulty in detection, it seems that it could be supported relatively easily.

Using a Type Alias

Will it be detected if a type alias is used for the Promise type?

type PromiseNumber = Promise<number>;

function foo(): PromiseNumber {
  return new Promise((resolve) => {
    setTimeout(() => resolve(42), 1000);
  });
}

export async function main() {
  foo();
}

In this example, it was detected. It seems that while complex type calculations are not possible, type aliases can be recognized.

Summary

In this article, I investigated the performance of Biome v2's "type inference" at the time of writing.

As a result, it was found that the performance is quite modest compared to type inference by a type checker, such as the inability to perform type inference in the return new Promise example, requiring a type annotation.

Still, there were behaviors that could be called inference, such as the internal handling of object and function types, the ability to handle generics, and the recognition that the return value of an async function is a Promise type even without a type annotation. It feels like it was created by properly facing the concept of "type" rather than something else disguised as type inference.

However, even when type annotations are explicitly stated, there seem to be limits to the calculation of types. It seemed impossible to calculate things like lookup types and conditional types.

It is surprising that even with such modest performance, it is sufficient to detect 75% of cases, as stated in the official blog.

I had a concern about Biome and other TypeScript-independent "type inference" features. That is, that a coding rule that does not fully utilize TypeScript's type system and only uses descriptions that Biome and others can understand might become widespread. If that happens, TypeScript's type system will essentially be forked.

Although Biome is still in the process of evolution, what do you think after seeing the results of this verification? Did it make you want to change your TypeScript practices to match Biome?

As for me, I would like to continue to watch how things will develop.

Biome's GritQL Plugin vs. ast-grep: Your Guide to AST-Based Code Transformation for JS/TS Devs

Herrington Darkholme — Fri, 06 Jun 2025 05:05:10 +0000

Introduction – Why AST Tools Matter for Native Linters

Maintaining consistent, high-quality code in large projects presents a significant challenge. While modern Rust-based linting tools deliver impressive performance for enforcing basic coding standards, they frequently fall short when developers require highly custom, project-specific patterns or automated, large-scale refactors across a codebase. This is where AST-based tools, particularly with the development of plugin systems in native linters, become essential.

In this report, we will delve into two prominent AST-based tools: Biome's new GritQL plugin and the established ast-grep. We will compare their syntax, performance, features, and more, providing a comprehensive guide to help developers choose the most suitable tool for their specific needs.

Meet the Contenders: A Quick Overview

Before diving into a head-to-head comparison, let's get acquainted with each tool individually, understanding their core functionalities and design philosophies.

Biome's GritQL Plugin: The New Kid on the Biome Block

Biome is a fast formatter and linter designed for web projects, intended to serve as a comprehensive replacement for tools like Prettier and ESLint. With its 2.0 beta release, Biome introduced a plugin system, initially supporting GritQL for defining custom lint rules.

The plugin operates by utilizing .grit files, which contain patterns written in GritQL. GritQL itself is a specialized query language designed for searching and transforming syntax trees. These .grit files are used to define custom diagnostic rules that Biome can then apply to a codebase. Configuration is straightforward: developers enable the plugin by adding the path to their .grit file within the plugins array in their biome.json configuration file.

As of the Biome 2.0 beta, the GritQL plugin is currently diagnostic-only. This means it excels at identifying and reporting specific code patterns, but it does not yet offer the capability to automatically fix them. However, the implementation of fixable rules, which will leverage GritQL's rewrite operator (=>), is a planned feature, indicating an ongoing development towards more comprehensive capabilities.

ast-grep: The Established AST Powerhouse

ast-grep stands as a mature and robust command-line tool, built on the high-performance Rust programming language. Its operational mechanism involves defining rules for searching, linting, and rewriting code using YAML files. ast-grep leverages tree-sitter, a powerful parsing library, to construct its Abstract Syntax Trees, enabling deep code understanding.

A significant advantage of ast-grep is its comprehensive set of capabilities, offering full fix and rewrite functionalities directly out of the box. This makes it a versatile tool for automated code modifications, ranging from simple linting autofixes to complex large-scale refactors. Its reliance on tree-sitter also provides extensive language support beyond just JavaScript, TypeScript, JSX, TSX, HTML, and CSS. It supports a wide array of programming languages including Python, Java, Go, Rust, and etc, making it a truly polyglot tool.

Biome's GritQL plugin extends Biome's existing linter primarily for custom diagnostics, whereas ast-grep is a foundational and versatile AST manipulation tool with a broader scope, including robust rewriting capabilities.

Head-to-Head: A Deep Dive into Comparison

Now that we've had a quick introduction to both tools, let's put them side-by-side and explore their differences across key aspects that matter to developers.

Syntax Showdown: How Rules Are Written

Understanding how to write rules is fundamental to using any AST-based tool. Let's examine equivalent examples in both Biome's GritQL plugin and ast-grep to compare their pattern languages and rule definition approaches.

Example 1: Detect console.log() Statements

Our goal here is to find all instances where console.log(...) is used, typically to identify debugging statements.

Biome GritQL Plugin (detect-console-log.grit):

For more detailed setup instructions, please kindly refer to the Isco's article.

language js (typescript, jsx);

// Pattern to match any call to console.log and register a warning
`console.log($$$arguments)` where {
  register_diagnostic(
    span = $$$arguments, // Highlight the arguments of the call
    message = "Avoid using console.log. Consider a dedicated logger or removing it for production.",
    severity = "warn"
  )
}

To enable this rule, add the path to your .grit file in your biome.json configuration:

{
    "linter": {
        "enabled": true,
        "rules": {
            "all": true
        }
    },
    "plugins": [ "./detect-console-log.grit"]
}

Explanation of Biome GritQL Rule:

This GritQL rule precisely targets console.log calls.

language js (typescript, jsx);: Sets the parser for JavaScript, TypeScript, and JSX.
`console.log($$$arguments)`: This is the literal code pattern. $$$arguments is a spread metavariable that matches any number of arguments passed to console.log().
where { register_diagnostic(...) }: When the pattern matches, register_diagnostic() is called to report an issue. It highlights the $$$arguments part of the code, provides a custom message, and sets the severity to "warn".

ast-grep (rules/no-console-log.yml):

For more detailed setup instructions, please kindly refer to makotot's article or the official site.

# rules/no-console-log.yml
id: no-console-log
language: TypeScript # or JavaScript
severity: warn
message: "Avoid using console.log. Consider a dedicated logger or removing it for production."
rule:
    pattern: console.log($$$ARGS)
    # fix: "" # Uncomment to automatically remove the console.log call

Explanation of ast-grep Rule:

This ast-grep rule similarly detects console.log statements using a declarative YAML structure.

id, language, severity, message: Standard fields providing rule identification, target language, warning level, and a descriptive message.
rule: pattern: console.log($$$ARGS): This defines the code pattern to match. $$$ARGS is a spread metavariable that captures any number of arguments to console.log().
# fix: "": A commented-out fix field demonstrates ast-grep's auto-rewriting capability; uncommenting it would remove the matched console.log() statement.

Syntax Takeaways for Example 1:

Pattern Matching: Both tools use a similar, intuitive pattern syntax (console.log($$$args)) with spread metavariables to match function calls irrespective of their arguments.
Diagnostic Reporting: GritQL uses a register_diagnostic() function within a where clause, while ast-grep uses direct YAML fields (message, severity) for rule metadata.
Rewrite Capability: ast-grep includes an explicit fix field for automated code transformations, a feature still planned for GritQL's direct rewrite operator.

Example 2: Detect React Components in createFileRoute Files

This rule aims to enforce a common architectural pattern in frameworks like TanStack Router: route files should primarily define routes and their data loaders, not React UI components. We want to flag any React component definitions (function or arrow function, named or default export) within files that import createFileRoute from @tanstack/react-router. This demonstrates a more complex, multi-step rule involving checking for an import and then searching for specific patterns conditionally.

Biome GritQL Plugin (no-components-in-route-file.grit):

Code snippet

// First check if this file imports createFileRoute from @tanstack/react-router
file(body=$program) where {
  // Check for the specific import within the entire file's AST
  $program <: contains bubble `import { $imports } from "@tanstack/react-router"` where {
      $imports <: contains `createFileRoute` // Ensure 'createFileRoute' is among the imported identifiers
  },
  // If the import exists, proceed to find component definitions anywhere within the file
  $program <: contains bubble or {
    // 1. Function declaration components (e.g., function MyComponent() { ... })
    `function $ComponentName($props) {
      $body
    }` where {
      $ComponentName <: r"^[A-Z][a-zA-Z0-9]*$", // Regex constraint: ensures it's a PascalCase identifier
      register_diagnostic(span=$ComponentName, message=`Component should not be defined directly in a route file. Move it to a separate UI component file.`, severity="error")
    },
    // 2. Arrow function components assigned to a variable (e.g., const MyComponent = () => { ... })
    `const $ComponentName = ($props) => {
      $body
    }` where {
      $ComponentName <: r"^[A-Z][a-zA-Z0-9]*$", // Regex constraint: ensures it's a PascalCase identifier
      register_diagnostic(span=$ComponentName, message=`Component should not be defined directly in a route file. Move it to a separate UI component file.`, severity="error")
    },
    // 3. Default exported function components (e.g., export default function MyComponent() { ... })
    `export default function $ComponentName($props) {
      $body
    }` where {
      register_diagnostic(span=$ComponentName, message="Default exported function components should not be defined in route files. Move it to a separate UI component file.", severity="error")
    },
    // 4. Default exported anonymous arrow function components (e.g., export default () => { ... })
    `export default ($props) => {
      $body
    }` where {
      register_diagnostic(span=$props, message="Default exported arrow functions should not be defined in route files. Move it to a separate UI component file.", severity="error")
    },
    // 5. Named exported function components (e.g., export function MyComponent() { ... })
    `export function $ComponentName($props) {
      $body
    }` where {
      $ComponentName <: r"^[A-Z][a-zA-Z0-9]*$",
      register_diagnostic(span=$ComponentName, message=`Exported component should not be defined directly in a route file. Move it to a separate UI component file.`, severity="error")
    }
  }
}

Explanation of Biome GritQL Rule:

This GritQL rule uses a powerful combination of top-level file matching, recursive searching (contains with bubble), and logical grouping (or and where) to implement the complex architectural check.

file(body=$program) where { ... }:
- file(): This is a GritQL function that signifies the entire source file being analyzed. It's the highest-level entry point for pattern matching, ensuring the rule considers the full context of the code.
- body=$program: This captures the entire Abstract Syntax Tree (AST) of the file into a metavariable named $program. This $program metavariable effectively becomes the root node for all subsequent searches and conditions within this rule.
- where { ... }: This clause introduces conditions that must all be met for the file() pattern to be considered a match and for any diagnostics within to be registered.
$program <: contains bubble \import { $imports } from "@tanstack/react-router"where { $imports <: contains \createFileRoute}:
- This is the first primary condition within the file()'s where clause. Its purpose is to check if the current file contains the specific import createFileRoute from @tanstack/react-router.
- $program <:: This syntax indicates that $program (the entire file's AST) must contain or match the pattern that follows.
- contains: This is a GritQL predicate that performs a search for the specified pattern within the given AST node ($program in this case). It only searches the immediate children of program. This is crucial for excluding elements that are not be at the top level of the file.
- bubble: When used with contains, the bubble clause creates a new, isolated scope for metavariables defined within the pattern it's applied to. In this specific pattern (`import { $imports } ...`), the metavariable is $imports. By using bubble, the $imports metavariable and its value are confined to this particular contains clause. This ensures that:
  - If there were other metavariables named $imports elsewhere in the rule, their values would not conflict with the $imports captured by this specific import statement match.
  - The subsequent where { $imports <: containscreateFileRoute} clause can directly refer to the $imports captured by this specific import pattern and apply a further condition to it, without ambiguity. It allows for modular reasoning about nested matches.
- `import { $imports } from "@tanstack/react-router"`: This is the literal code pattern GritQL searches for. The $imports metavariable captures the destructured part of the import statement (e.g., createFileRoute, createLoader).
- where { $imports <: containscreateFileRoute}: This is a nested condition applied specifically to the $imports metavariable captured by the import pattern. It uses contains again to verify that the string createFileRoute is present within the identifiers captured by $imports. This ensures we are only targeting files specifically using createFileRoute from the router library.
$program <: contains bubble or { ... }:
- This is the second primary condition in the file()'s where clause. This condition is only evaluated if the first condition (the import check) is met. Its purpose is to find any React component definitions within the file.
- contains bubble: Similar to the first condition, this performs a recursive search throughout the entire file's AST ($program) for any of the patterns defined within the or block. The bubble again ensures that any metavariables (like $ComponentName, $props, $body) captured within each individual component pattern are scoped locally to that specific pattern match. This means, for example, if there's a function MyComponent and later const MyOtherComponent, the $ComponentName metavariable will correctly capture "MyComponent" for the first match and "MyOtherComponent" for the second, without conflict.
- or { ... }: This is a logical OR operator. It means that if any of the patterns listed inside its curly braces match, this entire contains condition is satisfied. This is essential for detecting the various ways a React component can be defined (function declaration, arrow function, default export, named export).
- Individual Component Patterns (e.g., `function $ComponentName($props) { $body }`): Each block defines a common React component structure using GritQL's pattern syntax.
  - $ComponentName, $props, $body: These are metavariables capturing the component's name, props, and body respectively.
  - $ComponentName <: r"^[A-Z][a-zA-Z0-9]*$": This applies a regular expression predicate to the $ComponentName metavariable, ensuring the captured component name follows the PascalCase convention typical for React components (starts with an uppercase letter, followed by alphanumeric characters).
  - register_diagnostic(span=$ComponentName, message=..., severity="error"): This is the action that occurs when a component pattern successfully matches and all preceding where conditions (including the createFileRoute import check) are satisfied.
    - span=$ComponentName: Directs Biome to highlight the AST node corresponding to the component's name when reporting the issue.
    - message: The informative error message displayed to the developer.
    - severity: Sets the diagnostic level (e.g., "error", "warn").

In Summary for GritQL: The rule operates by first establishing that the file is a "route file" (by finding the createFileRoute import). Only if that condition holds true does it then proceed to recursively scan the same file for any common React component definitions. The bubble clause is critical for isolating the scope of metavariables within the contains patterns, ensuring that complex, multi-part rules can be built without unintended variable collisions or ambiguities across different matched sub-patterns.

ast-grep (rules/no-components-in-route-file.yml):

YAML

# rules/no-components-in-route-file.yml
id: no-components-in-route-file
language: TypeScript # or JavaScript, JSX, TSX
severity: error
message: "React components should not be defined directly in files that import createFileRoute. Move them to a separate UI component file."
rule:
  kind: program
  all: # Both conditions must be true for the rule to apply
  - has: # Condition 1: Check for the createFileRoute import
      pattern: import $$$IMP from "@tanstack/react-router"
      regex: createFileRoute # Ensure 'createFileRoute' is part of the imported identifiers
  - has: # Condition 2: Check for the presence of a React component pattern
      any: # Match any of these component definitions
      - pattern: function $COMPONENT($$$ARGS) { $$$ } # Function declaration
      - pattern: const $COMPONENT = ($$$ARGS) => $$$ # Arrow function assigned to a variable
      - pattern: export default ($$$PROPS) => $$$ # Default exported anonymous arrow function
      - pattern: export default function $COMPONENT($$$ARGS) { $$$ } # Default exported function
      - pattern: export function $COMPONENT($$$ARGS) { $$$ } # Named exported function
constraints: # Ensure PascalCase naming convention
  COMPONENT: { regex: "^[A-Z][a-zA-Z0-9]*" }

Explanation of ast-grep Rule:

This ast-grep rule utilizes YAML's declarative structure with kind, all, has, and any to define the same complex logical checks.

id, language, severity, message: These are standard metadata fields for an ast-grep rule, providing a unique identifier for the rule, specifying the programming language(s) it applies to, defining its diagnostic severity level (e.g., "error"), and providing the human-readable message that will be displayed when the rule is triggered.
rule: kind: program:
- kind: program: This specifies the target AST node type that the rule should be applied to. program typically represents the entire source file or compilation unit. This ensures the rule examines the complete code context, similar to GritQL's file().
all: [...]: This is a logical AND operator in ast-grep. It means that all of the sub-rules listed within its array must successfully match for the overall rule to be considered true. In this example, it enforces that both the import condition and the component presence condition must be met simultaneously.
First sub-rule: - has: pattern: import $$$IMP from "@tanstack/react-router" and regex: createFileRoute:
- This is the first condition under the all clause. It is designed to verify the presence of the createFileRoute import statement.
- has: This ast-grep rule field indicates that the current node (program in this context) must contain (as a descendant anywhere in its subtree) the specified pattern.
- pattern: import $$$IMP from "@tanstack/react-router": This is the structural pattern for the import statement. $$$IMP is a metavariable that captures the entire list of destructured identifiers within the curly braces (e.g., { createFileRoute, anotherImport }).
- regex: createFileRoute: This field applies a regular expression specifically to the text captured by the $$$IMP metavariable. It ensures that the exact string createFileRoute is present within that captured text.
Second sub-rule: - has: any: [...]:
- This is the second condition under the all clause. It is responsible for detecting various forms of React component definitions. This condition is only evaluated if the first condition (the createFileRoute import check) has passed.
- has: Similar to the first has rule, this performs a recursive search within the program node for any of the patterns defined within the nested any block.
- any: [...]: This is a logical OR operator in ast-grep. If any of the pattern rules listed in this array match within the program's AST, this has condition is satisfied. This flexibility allows the rule to catch all common ways React components are structured.
- Individual Component Patterns (e.g., - pattern: function $COMPONENT($$$ARGS) { $$$ }): Each item in the any array defines a specific structural pattern for a React component.
  - $COMPONENT, $$$ARGS, $$$ (wildcard for body): These are ast-grep's metavariables. $COMPONENT captures a single AST node (like a function name), $$$ARGS captures a sequence of nodes (like function arguments), and $$$ is a generic wildcard that matches any sequence of nodes (often used for a function body or statement block).
constraints: constraints field adds a check that $COMPONENT meta variable passes a PascalCase validation on component names.

In Summary for ast-grep: The rule is structured to apply to the entire file. It then uses an "AND" (all) condition to combine two primary "contains" (has) checks: one to confirm the presence of the createFileRoute import (with a regex to verify the specific identifier), and another to confirm the presence of any common React component patterns. If both checks pass, the rule triggers, reporting the architectural violation.

Syntax Takeaways for Example 2:

Complex Conditional Logic: This example highlights how both tools can implement rules requiring multiple conditions. GritQL uses chained where clauses with contains and bubble for deep searches and or for multiple alternatives. ast-grep uses all to combine necessary conditions and has with nested any to match a variety of component patterns.
Targeted Matching: Both tools can precisely target specific code constructs (imports, function declarations, arrow functions) and even apply additional constraints (like the PascalCase regex in GritQL for named components, which would require an additional regex or matches sub-rule in ast-grep for full parity).
Rule Scope: Both file(body=$program) in GritQL and kind: program in ast-grep indicate that the rule operates on the entire file's Abstract Syntax Tree.

Performance: Speed Matters

Performance is a critical factor for any code analysis tool, especially those integrated into linters that run frequently during development or within continuous integration/continuous deployment (CI/CD) pipelines. After all, linting speed is why we migrate from the more customizable eslint.

Real-World Case Study:

A real-world case study, documented in GitHub issue biomejs/biome#6210, highlighted a significant performance discrepancy between the two tools. In this scenario, a user created a custom Biome GritQL plugin rule designed to enforce specific conventions related to component definitions in files importing createFileRoute from @tanstack/react-router.

Original Biome GritQL rule performance: The initial version of this custom rule took a staggering 70 seconds to execute on the VS Code repository.
Biome performance without the rule: For context, Biome's base performance without this custom rule was remarkably fast, completing the same task in less than 2 seconds. This stark contrast clearly indicated that the custom GritQL rule was the primary bottleneck.
Equivalent ast-grep rule performance: An equivalent rule implemented in ast-grep performed significantly better, completing the same task on the same repository in a mere 0.5 seconds.
Optimized Biome GritQL rule performance: The Biome team and GritQL developers identified that the performance issue stemmed from unoptimized GritQL patterns. After optimization, which involved using more specific patterns like file(body=$program) and bubble, the Biome GritQL rule showed substantial improvement, adding only about 1 second of overhead to Biome's base performance.

Key Performance Takeaways:

ast-grep's general high performance: ast-grep consistently demonstrates superior performance. Its Rust core and optimized AST traversal mechanisms contribute to its speed, offering reliable and impressive performance across various scenarios.
Potential performance pitfalls with Biome's GritQL plugin (beta): As a newer tool still in beta, the initial implementation or the use of certain broad GritQL patterns (such as $program and contains without careful scoping) can lead to significant slowdowns. This indicates that while the tool is powerful, its current state requires careful consideration in rule design.
Importance of optimized patterns: The case study vividly illustrates that the way a GritQL rule is authored can drastically impact its performance within Biome. The Biome team and GritQL developers are actively aware of these considerations and are working on further optimizations and providing guidance for writing efficient patterns.

Conclusion on Performance: ast-grep currently offers superior and more consistent performance, especially for complex rules. Biome's GritQL plugin, being newer and in beta, shows promise but currently requires careful pattern authoring to avoid performance bottlenecks. However, performance is expected to improve as Biome and its GritQL integration continue to mature.

The stark contrast in initial performance (70 seconds for an unoptimized Biome GritQL rule versus 0.5 seconds for ast-grep) followed by Biome's optimization to 1 second overhead reveals a critical distinction. ast-grep delivers high performance as an inherent feature, largely out-of-the-box, due to its Rust core and optimized traversal. For Biome's GritQL plugin, however, achieving optimal performance is currently a challenge that the rule author must actively manage through careful pattern design and optimization. This means that the learning curve for Biome's GritQL isn't just about understanding its syntax, but also about mastering its performance characteristics and best practices for writing efficient rules. This can add a significant burden to developers, especially for complex or frequently run rules, potentially negating some of the benefits of integrating within the Biome ecosystem if not managed effectively.

Documentation & Learning Curve: Getting Started

The quality and accessibility of documentation, along with the overall learning curve, significantly impact a developer's ability to adopt and effectively use a new tool.

Biome GritQL Plugin Documentation:
Biome's official website provides documentation for its plugin system, covering how to enable plugins and the basic usage of the register_diagnostic() function. However, for the intricate details of the GritQL syntax itself—the language used to write the patterns—users need to refer to a separate official GritQL documentation, which is hosted on docs.grit.io.

Biome GritQL Plugin Learning Curve:
The learning curve for Biome's GritQL Plugin involves understanding two distinct systems. While Biome's plugin system is relatively straightforward to grasp, the GritQL language itself is more complex. GritQL has its own unique syntax and concepts, including patterns, predicates, where clauses, and specific built-in functions like contains and bubble. Furthermore, as demonstrated in the performance section, the need to write performant GritQL rules adds another layer of complexity to the learning curve. Currently, there isn't an interactive playground specifically integrated for Biome's GritQL plugin within the Biome ecosystem, although Grit.io does offer a general interactive playground for the GritQL language.

ast-grep Documentation:
ast-grep boasts comprehensive documentation available directly on its website, ast-grep.github.io. This includes detailed guides on its pattern syntax, rule configuration using YAML, advanced features, and API usage. A significant advantage for learning and testing patterns is the availability of an excellent interactive playground directly on its website (ast-grep.github.io/playground.html), which is invaluable for experimentation and rapid prototyping of rules.

ast-grep Learning Curve:
The YAML-based rule configuration of ast-grep is generally considered straightforward for developers to pick up. Its pattern syntax, which employs $META_VAR for single AST nodes and $$$VAR for sequences of nodes, is described as relatively intuitive for developers already familiar with code manipulation concepts. While understanding AST node kinds (derived from tree-sitter) can be beneficial for crafting more advanced rules, it is not strictly necessary for many common use cases. The tool also offers powerful relational (e.g., has, inside) and composite (e.g., all, any, not) rule fields, which may require some time to master for complex scenarios but provide significant flexibility.

Conclusion on Documentation & Learning:
ast-grep currently has a more mature and integrated documentation ecosystem, significantly enhanced by its valuable interactive playground. Its YAML and pattern syntax might feel more immediately accessible to some developers due to their more conventional structure. GritQL, while powerful, has a distinct syntax that necessitates dedicated learning. The fragmented documentation experience for Biome's plugin—requiring users to refer to Biome's site for plugin integration and Grit.io for the GritQL language itself—can make the initial learning journey slightly more fragmented and less cohesive.

The "split documentation" for Biome's GritQL plugin and the absence of a dedicated, integrated playground (requiring users to navigate to Grit.io for general GritQL experimentation) introduce unnecessary friction. Learning a new Domain Specific Language (DSL) like GritQL is already a cognitive hurdle; having to jump between disparate documentation sites and lacking integrated interactive tools exacerbates this challenge. In contrast, ast-grep's unified documentation and interactive playground streamline the entire learning process, making it much more approachable and efficient. This difference directly impacts how quickly a developer can become productive in writing custom rules, suggesting that a cohesive and interactive learning environment is a strong competitive advantage. Biome's current fragmented approach, though understandable for a beta product, poses a higher initial barrier to entry for new users.

Editor Support

Seamless integration with Integrated Development Environments (IDEs) and text editors is crucial for developer workflow and productivity.

Biome GritQL Plugin:
Biome's existing LSP integrations mean GritQL plugin diagnostics appear directly in editors like VSCode, JetBrains IDEs, and Neovim, just like other lint rules. However, dedicated editor support for authoring .grit files is limited, with only a VSCode extension available. Its LSP server currently struggles with wider adoption as other editors don't yet universally recognize the .grit file type for advanced authoring features.

ast-grep:

ast-grep naturally supports a wider range of editors for rule authoring because the file format is YAML. Diagnostics and code actions are available in any LSP-compliant editor:

VSCode: An official extension provides a rich Structural Search & Replace UI, diagnostics, Code Actions (quick fixes), and schema validation for rule.yml files, greatly streamlining rule creation.
Neovim: Support exists through nvim-lspconfig for its LSP server, complemented by specialized plugins like coc-ast-grep, telescope-sg, and grug-far.nvim.
LSP Server: Its standalone Language Server Protocol (LSP) server (ast-grep lsp) ensures seamless integration and broad compatibility for diagnostics and code actions in any LSP-compliant editor.

Conclusion on Editor Support:
ast-grep provides a more mature and comprehensive editor experience, particularly for authoring custom rules, with its dedicated VSCode UI, schema validation, and broad LSP compatibility. In contrast, Biome's GritQL plugin's rule authoring experience is currently more basic, constrained by limited editor-specific tooling and wider LSP recognition of .grit files. This makes ast-grep a more productive choice for frequent rule development.

Key Features at a Glance

This table provides a concise, side-by-side summary of the most important features and characteristics discussed throughout this comparison. For busy developers, a quick glance at this table allows for rapid assessment of the core differences and an initial evaluation of which tool aligns best with their immediate needs. It serves as a quick reference guide, reinforcing the detailed points made in the preceding sections and making the comparison digestible and actionable.

Aspect	Biome GritQL Plugin (v2.0 beta)	ast-grep
Core Functionality	Custom diagnostics for Biome linter	AST-based search, lint, and rewrite
Syntax Language	GritQL	YAML for rules, custom pattern syntax
Fix/Rewrite Capability	No (Planned Feature)	Yes (Built-in fix field in rules)
Performance (General)	Variable (can be slow if not optimized)	Generally very high (Rust-based, multi-threading)
Documentation Quality	Biome docs + GritQL docs (separate)	Comprehensive, integrated ast-grep docs
Debugging	Rudimentary	Official interactive playground
Learning Curve	Moderate to High (GritQL syntax + perf considerations)	Low to Moderate (YAML + intuitive patterns)
Editor Support	Diagnostics displayed via Biome's LSP	Rich VSCode extension, Neovim plugins, general LSP server
Standalone CLI Availability	No (part of Biome CLI)	Yes (`sg` command)

5. Choosing Your Champion: When to Pick Which Tool

The decision between Biome's GritQL plugin and ast-grep is not about one tool being universally "better," but rather about aligning with specific project needs, existing toolchains, and tolerance for beta features. Each tool has distinct strengths that make it more suitable for certain scenarios.

Choose Biome's GritQL Plugin if:

Existing Biome Investment: A development team is already heavily invested in the Biome ecosystem and seeks to extend its linting capabilities with custom rules without introducing another standalone tool.
Custom Linting Diagnostics: The primary need is to add custom diagnostic rules to Biome's linter specifically for JavaScript/TypeScript or CSS, and immediate requirements for automated fixes are not a top priority.
GritQL Comfort: The developers are comfortable with the GritQL syntax or are willing to learn its distinct approach and its nuances regarding performance optimization.
Acceptance of Beta Status and Future Fixes: The team is comfortable with the current beta status of the plugin and its present lack of autofixes, and is actively monitoring for this planned feature to be implemented in the future.
Optimized Performance Alignment: The performance characteristics, once rules are carefully optimized, align with the workflow's requirements for linting speed.

Choose ast-grep if:

Immediate Search and Rewrite Capabilities: Powerful, performant AST-based search and rewrite capabilities are needed right now, including robust autofixing and complex codemods.
Mature and Stable Tool: A mature, stable tool with a rich feature set and strong editor support (including a dedicated VSCode UI for structural search/replace and robust assistance in writing rules) is preferred.
Standalone CLI Tool: A standalone CLI tool is needed for scripting, performing one-off refactoring tasks, or integrating into CI pipelines independently of a specific linter.
YAML Preference: Developers prefer YAML for rule configuration and find its pattern syntax more immediately accessible and intuitive.
Complex Codemods and Autofixes: The goal is to build complex codemods or enforce coding standards with automated fixes, which is a core strength of ast-grep.
Interactive Playground: An interactive playground for developing and testing rules is an important part of the development workflow.

The decision between Biome's GritQL plugin and ast-grep is about aligning with specific project needs, existing toolchains, and tolerance for beta features. Biome's plugin is tightly integrated and serves as an enhancement for existing Biome users, simplifying custom linting within their established ecosystem. Conversely, ast-grep functions as a powerful, versatile standalone solution for broader AST manipulation tasks, including complex refactoring and multi-language support. This distinction means that if a team's primary goal is to extend Biome's linting, the plugin offers convenience. However, if the requirements extend to automated code transformations, polyglot analysis, or flexible CLI integration, ast-grep becomes the more capable and immediate choice. Developers should carefully evaluate their primary use case (e.g., custom linting within an existing Biome setup versus general AST search/rewrite/codemods), their existing development ecosystem, and their comfort level with beta features and dedicated learning curves to make the most informed decision.

6. Final Thoughts

Both Biome's GritQL plugin and ast-grep offer powerful AST-based code manipulation capabilities, moving beyond traditional text-based tools for custom standards, refactoring, and quality.

For immediate, robust AST manipulation with comprehensive fixing, broad language support, and strong editor integration, ast-grep is the clear and versatile choice. Biome's GritQL plugin, though in beta and currently diagnostic-only, is a promising addition for existing Biome users seeking integrated custom linting, with planned autofix features and performance optimizations on the horizon.

Ultimately, selecting between them depends on specific project needs: ast-grep for immediate, versatile AST control, or Biome's GritQL for extending an existing Biome setup and embracing its evolving ecosystem. The ongoing innovation from both integrated and standalone AST tooling promises an exciting future for code analysis and transformation.

Search Multi-language Documents in ast-grep

Herrington Darkholme — Wed, 24 Jul 2024 03:27:45 +0000

Introduction

ast-grep is a powerful structural code search tool that leverages syntax trees to find patterns in source code. This makes it more accurate and flexible than traditional text-based search tools.

ast-grep works well searching files of one single language, but it is hard to extract a sub language embedded inside a document.

However, in modern development, it's common to encounter multi-language documents. These are source files containing code written in multiple different languages. Notable examples include:

HTML files: These can contain JavaScript inside <script> tags and CSS inside <style> tags.
JavaScript files: These often contain regular expression, CSS style and query languages like graphql.
Ruby files: These can contain snippets of code inside heredoc literals, where the heredoc delimiter often indicates the language.

These multi-language documents can be modeled in terms of a parent syntax tree with one or more injected syntax trees residing inside certain nodes of the parent tree.

ast-grep now supports a feature to handle language injection, allowing you to search for code written in one language within documents of another language.

This concept and terminology come from tree-sitter's language injection, which implies you can inject another language into a language document. (BTW, neovim also embraces this terminology.)

Example: Search JS/CSS in the CLI

Let's start with a simple example of searching for JavaScript and CSS within HTML files using ast-grep's command-line interface (CLI).
ast-grep has builtin support to search JavaScript and CSS inside HTML files.

Using `sg run`: find patterns of CSS in an HTML file

Suppose we have an HTML file like below:



<style>
  h1 { color: red; }
</style>
<h1>
  Hello World!
</h1>
<script>
  alert('hello world!')
</script>

Running this ast-grep command will extract the matching CSS style code out of the HTML file!



sg run -p 'color: $COLOR'

ast-grep outputs this beautiful CLI report.



./test.html
2│  h1 { color: red; }

ast-grep works well even if just providing the pattern without specifying the pattern language!

Using `sg scan`: find JavaScript in HTML with rule files

You can also use ast-grep's rule file to search injected languages.

For example, we can warn the use of alert in JavaScript, even if it is inside the HTML file.



id: no-alert
language: JavaScript
severity: warning
rule:
  pattern: alert($MSG)
message: Prefer use appropriate custom UI instead of obtrusive alert call.

The rule above will detect usage of alert in JavaScript. Running the rule via sg scan.



sg scan --rule no-alert.yml

The command leverages built-in behaviors in ast-grep to handle language injection seamlessly. It will produce the following warning message for the HTML file above.



warning[no-alert]: Prefer use appropriate custom UI instead of obtrusive alert call.
  ┌─ ./test.html:8:3
  │
8 │   alert('hello world!')
  │   ^^^^^^^^^^^^^^^^^^^^^

How language injections work?

ast-grep employs a multi-step process to handle language injections effectively. Here's a detailed breakdown of the workflow:

File Discovery: The CLI first discovers files on the disk via the venerable ignore crate, the same library under ripgrep's hood.
Language Inference: ast-grep infers the language of each discovered file based on file extensions.
Injection Extraction: For documents that contain code written in multiple languages (e.g., HTML with embedded JS), ast-grep extracts the injected language sub-regions. At the moment, ast-grep handles HTML/JS/CSS natively.
Code Matching: ast-grep matches the specified patterns or rules against these regions. Pattern code will be interpreted according to the injected language (e.g. JS/CSS), instead of the parent document language (e.g. HTML).

Customize Language Injection: styled-components in JavaScript

You can customize language injection via the sgconfig.yml configuration file. This allows you to specify how ast-grep handles multi-language documents based on your specific needs, without modifying ast-grep's built-in behaviors.

Let's see an example of searching CSS code in JavaScript. styled-components is a library for styling React applications using CSS-in-JS. It allows you to write CSS directly within your JavaScript via tagged template literals, creating styled elements as React components.

The example will configure ast-grep to detect styled-components' CSS.

Injection Configuration

You can add the languageInjections section in the project configuration file sgconfig.yml.



languageInjections:
- hostLanguage: js
  rule:
    pattern: styled.$TAG`$CONTENT`
  injected: css

Let's break the configuration down.

hostLanguage: Specifies the main language of the document. In this example, it is set to js (JavaScript).
rule: Defines the ast-grep rule to identify the injected language region within the host language.

- `pattern`: The pattern matches styled components syntax where `styled` is followed by a tag (e.g., `button`, `div`) and a template literal containing CSS.
- the rule should have a meta variable `$CONTENT` to specify the subregion of injected language. In this case, it is the content inside the template string.

injected: Specifies the injected language within the identified regions. In this case, it is css.

Example Match

Consider a JSX file using styled components:



import styled from 'styled-components';

const Button = styled.button`
  background: red;
  color: white;
  padding: 10px 20px;
  border-radius: 3px;
`

exporrt default function App() {
  return <Button>Click Me</Button>
}

With the above languageInjections configuration, ast-grep will:

Identify the styled.button block as a CSS region.
Extract the CSS code inside the template literal.
Apply any CSS-specific pattern searches within this extracted region.

You can search the CSS inside JavaScript in the project configuration folder using this command:



sg -p 'background: $COLOR' -C 2

It will produce the match result:



./styled.js
2│
3│const Button = styled.button`
4│  background: red;
5│  color: white;
6│  padding: 10px 20px;
```

## Using Custom Language with Injection

Finally, let's look at an example of searching for GraphQL within JavaScript files.
This demonstrates ast-grep's flexibility in handling custom language injections.

### Define graphql custom language in `sgconfig.yml`.

First, we need to register graphql as a custom language in ast-grep. See [custom language reference](https://ast-grep.github.io/advanced/custom-language.html) for more details.

```yaml
customLanguages:
  graphql:
    libraryPath: graphql.so # the graphql tree-sitter parser dynamic library
    extensions: [graphql]   # graphql file extension
    expandoChar: $          # see reference above for explanation
```

### Define graphql injection in `sgconfig.yml`.

Next, we need to customize what region should be parsed as graphql string in JavaScript. This is similar to styled-components example above.

```yaml
languageInjections:
- hostLanguage: js
  rule:
    pattern: graphql`$CONTENT`
  injected: graphql
```

### Search GraphQL in JavaScript

Suppose we have this JavaScript file from [Relay](https://relay.dev/), a GraphQL client framework.

```js
import React from "react"
import { graphql } from "react-relay"

const artistsQuery = graphql`
  query ArtistQuery($artistID: String!) {
    artist(id: $artistID) {
      name
      ...ArtistDescription_artist
    }
  }
`
```

We can search the GraphQL fragment via this `--inline-rules` scan.

```sh
sg scan --inline-rules="{id: test, language: graphql, rule: {kind: fragment_spread}}"
```

Output

```sh
help[test]:
  ┌─ ./relay.js:8:7
  │
8 │       ...ArtistDescription_artist
  │       ^^^^^^^^^^^^^^^^^^^^^^^^^^^
```

## More Possibility to be Unlocked...

By following these steps, you can effectively use ast-grep to search and analyze code across multiple languages within the same document, enhancing your ability to manage and understand complex codebases.

This feature extends to various frameworks like [Vue](https://vuejs.org/) and [Svelte](https://svelte.dev/), enables searching for [SQL in React server actions](https://x.com/peer_rich/status/1717609270475194466), and supports new patterns like [Vue-Vine](https://x.com/hd_nvim/status/1815300932793663658).

Hope you enjoy the feature! Happy ast-grepping!

ast-grep got 6000 stars!

Herrington Darkholme — Sun, 19 May 2024 04:16:17 +0000

We are thrilled to announce that ast-grep, the powerful code search tool, has reached a stellar milestone of 6000 stars on GitHub! This is a testament to the community's trust in our tool and the continuous improvements we've made. Let's dive into the latest features and enhancements that make ast-grep the go-to tool for developers worldwide.

Feature Enhancements

Rewriters Addition: We've added support for rewriters #855, enabling complex code transformations and refactoring with ease. The new feature unlocks a novel functional programming like code rewrite scheme: find and patch. Check out our previous blog post for more details.

Error/Warning Suppression Support: The new feature #446 allows users to suppress specific errors or warnings via the code comment ast-grep-ignore. ast-grep also respects suppression comments in Language Server Protocol (LSP), making it easier to manage warnings and errors in your codebase.
Enhanced Rule Constraints: The ast-grep rule constraints previously only accepted pattern, kind and regex.
Now it accepts a full rule #855, providing more flexibility than ever before.

VSCode extension

The ast-grep VSCode extension is an official VSCode integration for this CLI tool. It unleashes the power of structural search and replace (SSR) directly into your editor.

Notable Features

Search: Find code patterns with syntax tree.
Replace: Refactor code with pattern.
Diagnose: Identify issues via ast-grep rule.

Performance Boost

Parallel Thread Output Fix: A significant fix #be230ca ensures parallel thread outputs are now guaranteed, boosting overall performance.

Architectural Evolution

Tree-Sitter Version Bump: We've upgraded to the latest tree-sitter version, enhancing parsing accuracy and speed. In future releases, we plan to leverage tree-sitter's new Web Assembly grammar to support even more languages.
Scan and Diff Merge: The refactor combines CombinedScan::scan and CombinedScan::diff for a more streamlined process.
Input Stream Optimization: Now, ast-grep avoids unnecessary input stream usage when updating all rules #943, making it possible to use sg scan --update-all.

Usability Improvements

Error Messaging for Rule File Parsing: The VSCode extension now provides clearer error messages #968 when rule file parsing fails, making troubleshooting a breeze.
Better Pattern Parsing: Improved expando character replacement #883 to make pattern .
More Permissive Patterns: Patterns have become more permissive #1087 that allows matching $METAVAR with different syntax kind.

Enhanced Error Reporting

We've introduced a suite of features to improve error reporting, making it easier to debug and refine your code:

Report undefined meta-variables, errors in fixes, unused rewriters, and undefined utility rules.
Add field ID errors for relational rules and optimize test updates to avoid erroneous reports.
Shift from reporting file counts to error counts for a more meaningful insight into code quality.

Language Support Expansion

Haskell Support: Haskell enthusiasts rejoice! ast-grep now supports Haskell via tree-sitter-haskell #1128, broadening our language coverage.

NAPI Advancements

NAPI Linux x64 musl Support: Our latest feat in NAPI #c4d7902 adds support for Linux x64 musl, ensuring wider compatibility and performance.

Thanks

As ast-grep continues to grow, we remain committed to providing a tool that not only meets but exceeds the expectations of our diverse user base.

We thank each and every one of you, espeically ast-grep's sponsors, for your support, contributions, and feedback that have shaped ast-grep into what it is today. Here's to many more milestones ahead!

Migrate to React 19 with ast-grep

Herrington Darkholme — Mon, 29 Apr 2024 04:00:02 +0000

Introduction

The release of React version 19 has been accompanied with a set of new features and enhancements.

However, upgrading to this new version requires certain modifications in the source code. This process can be quite taxing and repetitive, particularly for large codebases.

This article illustrates the usage of ast-grep, a tool designed to locate and substitute patterns in your codebase, towards easing your migration to React 19.

We will focus on three major codemods:

Use <Context> as a provider
Remove implicit ref callback return
Use ref as props and remove forwardRef

Prerequisite: Setting up ast-grep

Initially, you need to set up ast-grep. This can be carried out via npm:



npm install -g @ast-grep/cli

Once installed, the proper set up of ast-grep can be confirmed by running the command below:



ast-grep --version

Use `<Context>` as a provider

Let's kick off with the simplest modification: use as a provider.

React 19 uses <Context> as a provider instead of <Context.Provider>:



function App() {
  const [theme, setTheme] = useState('light');
  // ...
  return (
-    <UseTheme.Provider value={theme}>
+    <UseTheme value={theme}>
      <Page />
-    </UseTheme.Provider>
+    </UseTheme>

  );
}

With ast-grep, the pattern $CONTEXT.Provider can be found and replaced with $CONTEXT.
However, the pattern $CONTEXT.Provider could appear in multiple locations, requiring us to specifically look for it within a JSX opening and closing element.

We can utilize the ast-grep playground to find the correct names for JSX opening elements and JSX closing elements.

Afterwards, using inside and any, we can pinpoint that the pattern should exist within a JSX opening element and a JSX closing element.



id: use-context-as-provider
language: javascript
rule:
  pattern: $CONTEXT.Provider
  inside:
    any:
    - kind: jsx_opening_element
    - kind: jsx_closing_element
fix: $CONTEXT

Example playground link.

You can launch the rule from a YAML file using the command below:



ast-grep scan -r use-context-as-provider.yml

Remove implicit-ref-callback-return

Our next example is to remove implicit ref's return.

React 19 now supports returning a cleanup function from ref callbacks.

Due to the introduction of ref cleanup functions, returning anything else from a ref callback will now be rejected by TypeScript. The fix is usually to stop using implicit returns, for example:



- <div ref={current => (instance = current)} />
+ <div ref={current => {instance = current}} />

How can we find this pattern? We should find the pattern <div ref={$A => $B}/> where $B is not a statement block.

First, ast-grep can use pattern object to find jsx_attribute, which is the AST kind for the attribute in a JSX element.

You can use ast-grep's playground to find out the kind name.

Next, we need to find the pattern <div ref={$A => $B}/>. The pattern means that we are looking for a JSX element with a ref attribute that has a callback function.



pattern:
  context: <div ref={$A => $B}/>
  selector: jsx_attribute

Finally, we need to check if $B is not a statement block. We can use the constraints field to specify this condition.



constraints:
  B:
    not: {kind: statement_block}

Combining all these pieces, we get the following rule:



id: remove-implicit-ref-callback-return
language: javascript
rule:
  pattern:
    context: <div ref={$A => $B}/>
    selector: jsx_attribute
constraints:
  B:
    not: {kind: statement_block}
fix: $A => {$B}

Example playground link

Remove forwardRef

Let's explore our most complex change: Remove forwardRef. In our example, we will only focus on the simplest case where no arrow function nor TypeScript is involved.

The example code is as follows:



const MyInput = forwardRef(function MyInput(props, ref) {
  return <input {...props} ref={ref} />;
});

Let's first start simple. We can find the pattern forwardRef($FUNC).
However, the $FUNC does not capture the arguments of the function. We need to capture the arguments of the function and rewrite them in the fix.

This pattern rule captures the function arguments.



rule:
  pattern: forwardRef(function $M($PROPS, $REF) { $$$BODY })

Next, we need to rewrite the arguments of the function. The easiest way is to rewrite $PROPS as an object destructuring and to add ref into the object destructuring.



rule:
  pattern: forwardRef(function $M($PROPS, $REF) { $$$BODY })
fix: |-
  function $M({ref: $REF, ...$PROPS}) {
    $$$BODY
  }

Example playground link

Handle more complex cases

The above rule handles single identifier arguments gracefully. But it does not work for more complex cases like object destructuring, which is popular in React components.



const MyInput = forwardRef(function MyInput({value}, ref) {
  return <input value={value} ref={ref} />;
});

We can use rewriters to handle more complex cases. The basic idea is that we can break down the rewriting into two scenarios: object destructuring and identifiers.

The object rewriter captures the object destructuring pattern and extract the inner content.



id: object
rule:
pattern:
  context: ({ $$$ARGS }) => {}
  selector: object_pattern
fix: $$$ARGS

For example, the rewriter above will capture the {value} inside function MyInput({value}, ref) and extract value as $$$ARGS.

The identifier rewriter captures the identifier pattern and spreads it.



id: identifier
rule: { pattern: $P }
fix: ...$P

For example, the rewriter above will capture props and spread it as ...props.

Finally, we can use the rewriters field to register the two rules above.



rewriters:
- id: object
  rule:
    pattern:
      context: ({ $$$ARGS }) => {}
      selector: object_pattern
  fix: $$$ARGS
- id: identifier
  rule: { pattern: $P }
  fix: ...$P

And we then can use them in the transform field to rewrite the arguments and use them in the fix.



transform:
  NEW_ARG:
    rewrite:
      rewriters: [object, identifier]
      source: $PROPS
fix: |-
  function $M({ref: $REF, $NEW_ARG}) {
    $$$BODY
  }

Putting all these together, we get the final rule:



id: remove-forward-ref
language: javascript
rule:
  pattern: forwardRef(function $M($PROPS, $REF) { $$$BODY })
rewriters:
- id: object
  rule:
    pattern:
      context: ({ $$$ARGS }) => {}
      selector: object_pattern
  fix: $$$ARGS
- id: identifier
  rule: { pattern: $P }
  fix: ...$P
transform:
  NEW_ARG:
    rewrite:
      rewriters: [object, identifier]
      source: $PROPS
fix: |-
  function $M({ref: $REF, $NEW_ARG}) {
    $$$BODY
  }

Example playground link

Conclusion

Codemod is a powerful paradigm to automate code changes. In this article, we have shown how to use ast-grep to migrate to React 19.

We have covered three common changes: use as a provider, remove implicit-ref-callback-return, and remove forwardRef.

The examples here are for educational purposes and you are encouraged to use codemod.com to automate these changes in your codebase. codemod.com has curated rules that take care of these changes and more subtle edge cases.

You can adapt the example and explore ast-grep's power to automate more code changes.

ast-grep is also available on codemod.com.

Happy coding!

Explore useEffect Alternatives: Beyond the Well-Trodden Paths

Herrington Darkholme — Wed, 27 Mar 2024 23:24:50 +0000

React hooks have transformed the way we design and structure our React components - they've encouraged more functional and less class-based patterns. The useEffect hook is one of the most common hooks we use, and for good reason. It allows us to handle side effects - like data fetching, subscriptions, or manual DOM manipulations - in our functional components.

However, there may be cases where alternatives could suit better. Today, we'll explore both the well-known and lesser-known alternatives to useEffect.

Well-Known Alternatives

1. Computed State: useMemo

useMemo is a hook that returns a memorized value. This is typically used to optimize performance in scenarios where a computationally intensive value does not need to be recalculated unless its dependencies change. An instance where useMemo could be a great alternative is when we have complex computed state.

const computationIntensiveValue = useMemo(() => performHeavyComputation(a, b), [a, b]);

2. Event Handling: useCallback

For event handling scenarios, useCallback could be a better alternative. It's a hook that returns a memoized version of the callback that only changes if one of the dependencies has changed.

const memoizedCallback = useCallback(() => {
    eventHandler(a, b);
}, [a, b]);

3. State Management: useContext

useContext allows us to access the value of a context without wrapping a component in a <Context.Consumer> or using a class component. It's a perfect choice when it comes to lifting state up.

const contextValue = useContext(MyContext);

4. Data Fetching: useSWR

For data fetching, useSWR is a superb choice over useEffect. useSWR is a reusable state management tool for data fetching, which includes built-in handling for caching, retries, deduplication, and updates.

const { data, error } = useSWR('/api/data', fetcher)

Lesser-Known Alternatives

5. Resetting a component: use new `key`

Resetting a component sometimes might be useful to return the component to its initial state. Assigning a new key prop to a component makes React perceive the latter as a completely new component, thereby remounting it.

<MyComponent key={uniqueId} />

6. Resetting some state: setState in render

Instead of using useEffect, setting state directly in the render method is a viable option for some cases. This might seem counter-intuitive, but can be effective when it needs to reset specific state values during rendering.

if (needToReset) {
  setState(initialState);
}

7. External data source: useSyncExternalStore

The useSyncExternalStore hook provides a way to read from and subscribe to an external (mutable) source. This can be ideal when dealing with external data sources.

const state = useSyncExternalStore(store.subscribe, store.getState);

Conclusion

Using useEffect for everything might seem like a go-to solution, but there's a plethora of hooks and alternatives readily available for particular problems. It's important to understand these to get the best out of React. Use the most suitable tool for your issue and make your React applications shine!

Remember, the beauty of Hooks lies in the orchestration of simplicity and functionality, making React a more potent and friendly framework. Stay curious, explore more, and keep coding innovative solutions!

ast-grep VSCode: A Powerful Tool for Structural Search and Replace

Herrington Darkholme — Sun, 03 Mar 2024 02:10:56 +0000

Hi, I'm Herrington, the author of ast-grep.

If you've ever searched code with regular expressions, you may have struggled with matching multiple lines, nested structures, or ignoring comments.

Let me introduce ast-grep VSCode, a new extension leveraging the power of structural search and replace (SSR) to help you perform more precise and efficient search and replace.

The Limitations of Textual Search and Replace

Suppose you want to refactor your JavaScript code to replace the lodash _.filter function with the native Array.prototype.filter method. A simple text search and replace might look like this:

// Find
_.filter\((\.+), (.+)\)
// Replace
$1.filter($2)

This might work for some cases, but it has several limitations:

It can only match single-line expressions. If your code spans multiple lines, you'll miss some matches or get incorrect replacements.
It can't handle nested structures like parentheses, brackets, or braces. If your code has complex expressions, you'll get incorrect matches or replacements.
It can't ignore comments or other irrelevant parts of the code. If your code has comments that contain the search pattern, you'll get unwanted matches or replacements.
It requires you to use match groups or named capture groups to preserve the arguments of the function. This can be tedious and error-prone, especially with many arguments or nested functions.

Structural Search and Replace Comes to the Rescue

Can we make our search algorithm smarter, understand our code better, and be easier to use? Yes! Structural search and replace (SSR) comes to the rescue!

Structural search and replace (SSR) is a technique that allows you to find and modify code patterns based on their syntax and semantics, not just their text. Instead of treating code as plain text, SSR treats code as a collection of nodes with types, properties, and relationships.

ast-grep is a command-line tool that implements SSR. The query for the lodash example above is quite simple.

// Search pattern:
_.filter($ARR, $FUNC)
// Rewrite:
$ARR.filter($FUNC)

The pattern illustrates the basic usage of ast-grep. $ARR and $FUNC are meta-variables. Meta-variables are like the dot . in regular expressions, except they match AST nodes instead of characters. You can also use captured meta-variables in the rewrite pattern.

Other than the meta-variables, I hope the pattern and rewrite are self-explanatory.

This query has several advantages over the text search and replace:

It can match expressions across multiple lines, as long as they are syntactically valid.
It can handle nested structures like parentheses, brackets, or braces, as they are part of the AST.
It can ignore comments or other irrelevant parts of the code, as they are not part of the AST.
It does not require match groups or named capture groups, as the meta-variables are accessed by their names in the search pattern.

Unique Features of ast-grep

ast-grep uses the tree-sitter library, a fast and robust parser for many programming languages. ast-grep allows you to write queries using a simple pattern syntax that resembles code and apply them to files or directories of code. Some of the unique features of ast-grep are:

It supports many languages, including JavaScript, TypeScript, Python, Ruby, Java, C#, Go, Rust, and more. You can also add support for new languages by registering tree-sitter grammars in the configuration.
It is written in Rust, which makes it very fast and memory-efficient. It can process large codebases in a matter of seconds.
It has a rich set of options and flags, such as dry run, interactive mode, color output, and more. You can customize your SSR experience to suit your needs and preferences.

But, ast-grep until now only has a command-line interface. Can we have its power right near our hands instead of switching between terminals and editors?

ast-grep VSCode: Bridging the CLI and the Editor

ast-grep VSCode is a new extension that integrates ast-grep with Visual Studio Code, one of the most popular code editors. With ast-grep VSCode, you can use SSR within your editor, without leaving your workflow.

Structural Search, Replace, and More

Some features of ast-grep VSCode include:

It provides a user interface for writing and executing SSR queries, and you can see the results of your queries in a sidebar, with previews and diffs.
It also supports linting and code fix. You can set up an ast-grep project and write custom rules tailored to your needs.
It feels like a native VSCode feature, with seamless integration and consistent design.

Feature	Screenshot
Search Pattern
Search In Folder
Replace Preview
Commit Replace
Code Linting

Comparing with Other SSR Tools

There are other SSR tools and extensions available. However, I believe ast-grep VSCode is one of the best SSR extensions for VSCode because:

It has good performance, backed by a multi-threaded CLI written in a native language.
It supports multiple languages, leveraging the tree-sitter grammars widely used and maintained by the community.
It has a user-friendly and intuitive interface that feels like a VSCode built-in feature. See it in action.

Finally, I want to highlight some React techniques used in ast-grep VSCode that make it fast and responsive:

useSyncExternalStore was used to manage streaming results from ast-grep CLI. This hook allows components to subscribe to an external mutable source of data and update the rendering accordingly. This way, the extension can show the results as soon as they are available.
useDeferredValue deferred rendering the result list. This hook can avoid blocking user input and improve the perceived performance of the UI by delaying the update of a derived state until the next concurrent render.
The extension carefully used plenty of memo and CSS tricks to reduce the JavaScript workload.

Conclusion

I hope this article helps you understand the benefits of SSR and the features of ast-grep VSCode. If you are interested in trying it out, you can install it from the VSCode Marketplace. ast-grep VSCode is still in development and has a lot of room for improvement. I would love to hear your feedback and suggestions, so feel free to open an issue or a pull request on GitHub. I also want to thank SoonIter, Steven Love, Nyakku Shigure, and ssr.nvim for their contribution and inspiration!

Happy grepping!

Find & Patch: A Novel Functional Programming like Code Rewrite Scheme

Herrington Darkholme — Thu, 08 Feb 2024 08:29:30 +0000

Introduction

Code transformation is a powerful technique that allows you to modify your code programmatically. There are many tools that can help you with code transformation, such as Babel/biome for JavaScript/TypeScript, libcst for Python, or Rector for PHP. Most of these tools use imperative APIs to manipulate the abstract syntax tree (AST) of your code.

In this post, we will introduce a different approach to code transformation called Find & Patch.

This scheme lets you rewrite complex code using a fully declarative Domain-Specific Language (DSL). While the scheme is powerful, the underlying concept is simple: find certain nodes, rewrite them, and recursively repeat the rewriting.

The idea of Find & Patch comes from developing ast-grep, a tool using AST to find and replace code patterns. We realized that this approach can be generalized and extended to support more complex and diverse code transformations!

At the end of this article, we will compare Find & Patch to functional programming on the tree of syntax nodes. You can apply filter nodes using rule, map them via transform, and compose them with rewriters.

This gives you a lot of flexibility and expressiveness to manipulate your code!

What is ast-grep?

ast-grep is a tool to search and rewrite code based on ASTs. It is like grep for code, but with the power of ASTs.
More concretely, ast-grep can find code patterns using its rule system. It can also rewrite the matched code using meta-variables based on the rule.

ast-grep's rewriting can be seen as two steps: finding target nodes and patching them with new text.

Find and Patch: How ast-grep Rewrites Code

The basic rewriting workflow of ast-grep is like below:

Find: search the nodes in the AST that match the rewriter rules (hence the name ast-grep).
Rewrite: generate a new string based on the matched meta-variables.
Patch: replace the node text with the generated fix.

Let's see a simple example: replace console.log with logger.log. The following rule will do the trick.

rule:
  pattern: console.log($MSG)
fix: logger.log($MSG)

The rule above is quite straightforward. It matches the console.log call, using the pattern, and replaces it with the logger.log call.
The meta-variable $MSG captures the argument of console.log and is used in the fix field.

ast-grep also has several other fields to fine-tune the process. The core fields in ast-grep's rule map naturally to the idea of Find & Patch.

Find
- Find a target node based on the rule
- Filter the matched nodes based on constraints
Patch
- Rewrite the matched meta-variable based on transform
- Replace the matched node with fix, which can use the transformed meta-variables.

Limitation of the Current Workflow

However, this workflow has a limitation: it can only replace one node at a time, which means that we cannot handle complex transformations that involve multiple nodes or lists of nodes.

For example, suppose we want to rewrite barrel imports to single imports. A barrel import is a way to consolidate the exports of multiple modules into a single convenient module that can be imported using a single import statement. For instance:

import {a, b, c} from './barrel';

This imports three modules (a, b, and c) from a single barrel file (barrel.js) that re-exports them.

Rewriting this to single imports has some benefits, such as reducing bundle size or avoiding conflicting names.

import a from './barrel/a';
import b from './barrel/b';
import c from './barrel/c';

This imports each module directly from its own file, without going through the barrel file.

With the simple "Find and Patch" workflow, we cannot achieve this transformation easily. We either have to rewrite the whole import statement or rewrite each identifier one by one. We cannot replace the whole import statement because we cannot process the multiple identifiers, which requires processing a list of nodes at one time.
Can we rewrite the identifiers one by one? This also fails because we cannot replace the whole import statement, so there will be unwanted import statement text surrounding the identifiers.

// we cannot rewrite the whole import statements
// because we don't know how to rewrite a, b, c as a list
import ??? from './barrel';
// we cannot rewrite each identifier
// because the replaced text is inside the import statement
import { ??, ??, ?? } from './barrel';

We need a better way to rewrite code that involves multiple nodes or lists of nodes. And here comes Find & Patch.

Extend the Concept of `Find` and `Patch`

Let's reflect: what limits us from rewriting the code above?

Our old workflow does not allow us to apply a rule to multiple sub-nodes of a node. (This is like not being able to write for loops.)

Nor does it allow us to generate different text for different sub-nodes in a rule. (This is like not being able to write if/switch statements.)

I initially thought of adding list comprehension to transform to overcome these limitations. However, list comprehension will introduce more concepts like loops, filters and probably nested loops. I prefer having Occam's razor to shave off unnecessary constructs.

Luckily, Mosenkis proposed the refreshing idea that we can apply sub-rules, called rewriters, to specific nodes during matching. It can elegantly solve the issue of processing multiple nodes with multiple different rules!

The idea is simple: we will add three new, but similar, steps in the rewriting step.

Find a list of different sub-nodes under a meta-variable that match different rewriters.
Generate a different fix for each sub-node based on the matched rewriter sub-rule.
Join the fixes together and store the string in a new metavariable for later use.

The new steps are similar to the existing "Find and Patch" workflow. It is like recursively applying the old workflow to matched nodes!

We can, taking the previous barrel import as an example, first match the import statement and then apply the rewriter sub-rule to each identifier.

Intriguing Example

The idea above is implemented by a new rewriters field and a new rewrite transformation.

Our first step is to write a rule to capture the import statement.

rule:
  pattern: import {$$$IDENTS} from './barrel'

This will capture the imported identifiers a, b, c in $$$IDENTS.

Next, we need to transform $$$IDENTS to individual imports.

The idea is that we can find the identifier nodes in the $$$IDENT and rewrite them to individual imports.

To do this, we register a rewriter that acts as a separate rewriter rule for each identifier.

rewriters:
- id: rewrite-identifer
  rule:
    pattern: $IDENT
    kind: identifier
  fix: import $IDENT from './barrel/$IDENT'

The rewrite-identifier above will:

First, find each identifier AST node and capture it as $IDENT.
Rewrite the identifier to a new import statement.

For example, the rewriter will change identifier a to import a from './barrel/a'.

We can now apply the rewriter to the matched variable $$$IDENTS.

The counterpart of rewriter is the rewrite transformation, which applies the rewriter to a matched variable and generates a new string.

The yaml fragment below uses rewrite to find identifiers in $$$IDENTS, as specified in rewrite-identifier's rule,
and rewrites it to single import statement.

transform:
  IMPORTS:
    rewrite:
      rewriters: [rewrite-identifer]
      source: $$$IDENTS
      joinBy: "\n"

Note the joinBy field in the transform section. It specifies how to join the rewritten import statements with a newline character. This means that each identifier will generate a separate import statement, followed by a newline.

Finally, we can use the transformed IMPORTS in the fix field to replace the original import statement.

The final rule will be like this. See the online playground.

rule:
  pattern: import {$$$IDENTS} from './barrel'
rewriters:
- id: rewrite-identifer
  rule:
    pattern: $IDENT
    kind: identifier
  fix: import $IDENT from './barrel/$IDENT'
transform:
  IMPORTS:
    rewrite:
      rewriters: [rewrite-identifer]
      source: $$$IDENTS
      joinBy: "\n"
fix: $IMPORTS

Similarity to Functional Programming

Find & Patch is a scheme that allows us to manipulate the syntax tree of the code in a declarative way.

It reminds me of Rust declarative macro since both Find & Patch and Rust declarative macro can:

Match a list of nodes/tokens based on patterns: ast-grep's rule vs. Rust macro pattern matcher.
Break nodes/tokens into sub parts: ast-grep's metavariable vs. Rust macro variable.
Recursively use subparts to call other rewrite/macros.

The idea can be further compared to functional programming! We can use different rules to match and transform different sub-nodes of the tree, just like using pattern matching in functional languages. We can also apply rules to multiple sub-nodes at once, just like using for-comprehension or map/filter/reduce. Moreover, we can break down a large syntax tree into smaller sub-trees by using meta-variables, just like using destructuring or elimination rules in functional languages. But all of these can be boiled down to two simple idea: Finding nodes and Patching nodes!

Find & Patch is a simple and elegant scheme that is tailored for AST manipulation, but it can achieve similar transformations as a general-purpose functional programming language doing rewrites!

We can think of Find & Patch as a form of "Functional Programming" over the AST! And they both have the same acronym btw.

Hope you find this scheme useful and interesting, and I sincerely invite you to try it out with ast-grep. Thank you for reading~

Forem: Herrington Darkholme

ast-grep 0.42: The Answer to Code Searching

Parameterized Utilities (Experimental)

The Problem

The Solution

Key Usage Rules

Advanced: How It Works Under the Hood

More ESQuery-Style Selectors

:has(selector)

:not(selector)

:is(selector, moreSelector, ...)

:nth-child(An+B) and :nth-child(An+B of selector)

LSP: Diagnostics for Injected Languages

Next Steps

Agent Calculus: A Unified Framework for AI Agent Design

Abstract

1. Introduction & Motivation

The Problem

The Solution

2. Core Assumptions

3. Fundamental Definitions

3.1 LLM as Pure Function

3.2 Context vs World

3.3 Agent Decomposition

4. The Entity Abstraction

4.1 Entity Definition

4.2 Entity Types by Loading Strategy

4.3 Entity Dimensions

4.4 Examples

5. The Harness

5.1 Load Function

5.2 Execute Function

5.3 Context Window Management

Strategy 1: Relevance Filtering

Strategy 2: Progressive Compression

Strategy 3: Hierarchical Summarization

Strategy 4: Swap Full↔Digest

5.4 Atomic Load Operations

6. The Agent Loop

6.1 Pseudocode

6.2 Example Execution Trace

7. Multi-Agent Design Patterns

7.1 Pattern: Tool-Use Agent

7.2 Pattern: Skill-Enhanced Agent

7.3 Pattern: Subagent Spawning

7.4 Pattern: RAG (Retrieval-Augmented Generation)

7.5 Pattern: ReAct (Reasoning + Acting)

7.6 Pattern: Reflection

7.7 Pattern: Multi-Agent Collaboration

8. Advanced Topics

8.1 Dynamic Tool Loading

8.2 Entity Discovery Mechanisms

8.3 Tool Data Handling Strategies

8.4 Context Compression Strategies

8.5 JIT (Just-In-Time) Context Loading

8.6 Multi-Level Tool Descriptions

9. Integration with Existing Systems

9.1 Mapping to Real Agent Frameworks

9.2 RAG Systems

10. Future Directions & Open Questions

10.1 Entity Discovery as a Graph

10.2 Entity-Provided Processing Instructions

10.3 Learned Context Management

10.4 Hierarchical Entities

10.5 Entity Lifecycle Hooks

10.6 Cross-Agent Entity Sharing

10.7 Speculative Entity Loading

10.8 Differential Context Updates

10.9 Entity Versioning

10.10 Meta-Entities

11. Conclusion

Key Insights

Practical Value

Next Steps

References

Appendix: Notation Reference

Koka.py: Type-Checked Dependency Injection and Error Handling in Python

The Problem: Python's Hidden Dependencies and Exceptions

What Are Algebraic Effects? (A Practical Take)

The Inspiration Chain

`:has(selector)`

`:not(selector)`

`:is(selector, moreSelector, ...)`

`:nth-child(An+B)` and `:nth-child(An+B of selector)`

How `yield from` Achieves This

The `Eff` Type

How `Dep[T]` Works

How `Err[E]` Works

The `yield from` Version (For Contrast)

Why Not `async/await`?

Using `new Promise`

Trying Out `Promise`

Using `sg run`: find patterns of CSS in an HTML file

Using `sg scan`: find JavaScript in HTML with rule files