Providers Guide

Each language provider extracts semantic chunks according to that language's idioms. This guide covers language-specific behavior and what to expect from each provider.

Go

Package: github.com/zoobz-io/chisel/golang

Dependencies: None (uses stdlib go/parser)

Extracts:

Construct	Kind	Symbol Format
Package doc	`module`	Package name
Function	`function`	Function name
Method	`method`	`Receiver.Method`
Struct	`class`	Type name
Interface	`interface`	Type name
Type alias	`type`	Type name

Example:

// Package auth provides authentication utilities.
package auth

// User represents an authenticated user.
type User struct {
    ID string
}

// Authenticate validates credentials.
func Authenticate(u, p string) (*User, error) { ... }

// Validate checks if a user session is valid.
func (u *User) Validate() bool { ... }

Produces:

[module]    auth         (lines 1-2)
[class]     User         (lines 4-7)
[function]  Authenticate (lines 9-9)
[method]    User.Validate (lines 11-11)

Notes:

Package documentation is extracted as a module chunk
Methods include receiver type in symbol: User.Validate
Documentation comments are included in chunk content
Requires syntactically valid Go (parse errors fail the entire file)

TypeScript

Package: github.com/zoobz-io/chisel/typescript

Dependencies: go-tree-sitter (cgo)

Extracts:

Construct	Kind	Symbol Format
Function declaration	`function`	Function name
Arrow function	`function`	Variable name or `<anonymous>`
Class	`class`	Class name
Method	`method`	Method name
Interface	`interface`	Interface name
Type alias	`type`	Type name

Example:

interface User {
    id: string;
    email: string;
}

class UserService {
    async getUser(id: string): Promise<User> {
        return this.db.find(id);
    }
}

function createService(): UserService {
    return new UserService();
}

const helper = (x: number) => x * 2;

Produces:

[interface] User          (lines 1-4)
[class]     UserService   (lines 6-10)
[method]    getUser       (lines 7-9)   context: [class UserService]
[function]  createService (lines 12-14)
[function]  helper        (lines 16-16)

Notes:

Methods have their parent class in Context
Arrow functions assigned to const use the variable name
Anonymous functions use <anonymous> as symbol

JavaScript

Package: github.com/zoobz-io/chisel/typescript (use NewJavaScript())

Dependencies: go-tree-sitter (cgo)

Uses the same parser as TypeScript but configured for JavaScript. Behavior is identical except:

No type annotations
No interfaces or type aliases

provider := typescript.NewJavaScript()
chunks, err := provider.Chunk(ctx, "app.js", source)

Python

Package: github.com/zoobz-io/chisel/python

Dependencies: go-tree-sitter (cgo)

Extracts:

Construct	Kind	Symbol Format
Function	`function`	Function name
Method	`method`	Method name
Class	`class`	Class name
Decorated function	`function`	Function name

Example:

class UserService:
    """Manages user operations."""

    def __init__(self, db):
        self.db = db

    def get_user(self, user_id: str) -> User:
        """Fetch a user by ID."""
        return self.db.find(user_id)

@dataclass
class User:
    id: str
    email: str

def create_service() -> UserService:
    return UserService(Database())

Produces:

[class]    UserService    (lines 1-9)
[method]   __init__       (lines 4-5)    context: [class UserService]
[method]   get_user       (lines 7-9)    context: [class UserService]
[class]    User           (lines 11-14)
[function] create_service (lines 16-17)

Notes:

Decorators are included in the chunk content
Docstrings are part of the chunk
__init__ and other dunder methods are extracted as methods

Rust

Package: github.com/zoobz-io/chisel/rust

Dependencies: go-tree-sitter (cgo)

Extracts:

Construct	Kind	Symbol Format
Function	`function`	Function name
Method (in impl)	`method`	Method name
Struct	`type`	Struct name
Enum	`enum`	Enum name
Trait	`interface`	Trait name
Impl block	`class`	Type name
Module	`module`	Module name

Example:

pub struct User {
    pub id: String,
    pub email: String,
}

impl User {
    pub fn new(id: String, email: String) -> Self {
        User { id, email }
    }

    pub fn validate(&self) -> bool {
        !self.id.is_empty()
    }
}

trait Authenticatable {
    fn authenticate(&self) -> bool;
}

enum Status {
    Active,
    Inactive,
}

Produces:

[type]      User           (lines 1-4)
[class]     User           (lines 6-14)   # impl block
[method]    new            (lines 7-9)    context: [impl User]
[method]    validate       (lines 11-13)  context: [impl User]
[interface] Authenticatable (lines 16-18)
[enum]      Status         (lines 20-23)

Notes:

Structs are type, impl blocks are class
Methods know their impl block via Context
Traits map to interface
Enums have their own kind

Markdown

Package: github.com/zoobz-io/chisel/markdown

Dependencies: None

Extracts:

Construct	Kind	Symbol Format
Header	`section`	Header text (without `#`)

Example:

# Installation

Install the package:

```bash
go get github.com/example/pkg

Configuration

Set the following environment variables:

Required Variables

API_KEY: Your API key

Optional Variables

DEBUG: Enable debug mode


Produces:

```text
[section] Installation        (lines 1-7)
[section] Configuration       (lines 9-11)
[section] Required Variables  (lines 13-15)
[section] Optional Variables  (lines 17-19)

Notes:

Each header starts a new section
Section content continues until the next header of equal or higher level
Nested headers create nested sections (no context chain currently)

Next Steps

Testing Guide — Test code that uses chisel
Troubleshooting — Common issues
API Reference — Function signatures