shards

Documentation

Index

• Constants
• Variables
• func Clean(_ context.Context, _ *config.Config, dir string, dryRun bool) error
• func CommentPrefix(ext string) string
• func CreateZipFile(repoDir string, onlyFiles []string) (string, error)
• func DryRunList(repoDir string) ([]string, error)
• func Generate(ctx context.Context, cfg *config.Config, dir string, opts GenerateOptions) error
• func Header(prefix string) string
• func Hook(port int) error
• func PrintLanguageBarChart(stats []LangStat, totalFiles int)
• func Render(dir string, opts RenderOptions) error
• func RenderAll(repoDir string, cache *Cache, files []string, dryRun bool) (int, error)
• func RenderGraph(filePath string, cache *Cache, prefix string) string
• func ShardFilename(sourcePath string) string
• func Watch(ctx context.Context, cfg *config.Config, dir string, opts WatchOptions) error
• func WriteShard(repoDir, shardPath, content string, dryRun bool) error
• type Cache
  • func NewCache() *Cache
  • func (c *Cache) Build(ir *api.ShardIR)
  • func (c *Cache) FuncName(fnID string) string
  • func (c *Cache) SourceFiles() []string
  • func (c *Cache) TransitiveDependents(filePath string) map[string]bool
• type CallerRef
• type Daemon
  • func NewDaemon(cfg DaemonConfig, client *api.Client) *Daemon
  • func (d *Daemon) Run(ctx context.Context) error
• type DaemonConfig
• type FuncInfo
• type GenerateOptions
• type GraphStats
• type LangStat
  • func LanguageStats(files []string) []LangStat
• type RenderOptions
• type WatchEvent
• type WatchOptions
• type Watcher
  • func NewWatcher(repoDir string, pollInterval time.Duration) *Watcher
  • func (w *Watcher) Events() <-chan []WatchEvent
  • func (w *Watcher) Run(ctx context.Context)

Constants

const ShardExt = "graph"

ShardExt is the extension tag for the combined shard file.

Variables

var SourceExtensions = map[string]bool{
	".ts": true, ".js": true, ".mjs": true, ".jsx": true, ".tsx": true,
	".go": true, ".py": true, ".rb": true, ".rs": true,
	".java": true, ".cs": true, ".cpp": true, ".c": true, ".h": true,
	".swift": true, ".kt": true,
}

SourceExtensions are the file extensions that get shards.

Functions

func Clean

func Clean(_ context.Context, _ *config.Config, dir string, dryRun bool) error

Clean removes all .graph.* shard files from the directory tree.

func CommentPrefix

func CommentPrefix(ext string) string

CommentPrefix returns the language-appropriate comment prefix.

func CreateZipFile

func CreateZipFile(repoDir string, onlyFiles []string) (string, error)

CreateZipFile creates a zip archive of the repo directory, respecting filters, writes it to a temporary file, and returns the path. The caller is responsible for removing the file. If onlyFiles is non-nil, only those relative paths are included (incremental mode).

func DryRunList

func DryRunList(repoDir string) ([]string, error)

DryRunList returns the list of files that would be included in the zip.

func Generate

func Generate(ctx context.Context, cfg *config.Config, dir string, opts GenerateOptions) error

Generate uploads a zip, builds the graph cache, and renders all shards.

func Header

func Header(prefix string) string

Header returns the @generated header line.

func Hook

func Hook(port int) error

Hook reads a Claude Code PostToolUse JSON event from stdin and sends a UDP notification to the watch daemon for any source file written or edited.

func PrintLanguageBarChart

func PrintLanguageBarChart(stats []LangStat, totalFiles int)

PrintLanguageBarChart writes a compact bar chart of language stats to stderr.

func Render

func Render(dir string, opts RenderOptions) error

Render renders shards from the existing cache without fetching from the API.

func RenderAll

func RenderAll(repoDir string, cache *Cache, files []string, dryRun bool) (int, error)

RenderAll generates and writes .graph shards for the given source files. Returns the count of shards written.

func RenderGraph

func RenderGraph(filePath string, cache *Cache, prefix string) string

RenderGraph produces a combined .graph shard with deps, calls, and impact sections.

func ShardFilename

func ShardFilename(sourcePath string) string

ShardFilename generates the .graph shard path. Example: "src/Foo.tsx" → "src/Foo.graph.tsx"

func Watch

func Watch(ctx context.Context, cfg *config.Config, dir string, opts WatchOptions) error

Watch runs generate on startup, then enters daemon mode.

func WriteShard

func WriteShard(repoDir, shardPath, content string, dryRun bool) error

WriteShard writes a shard file with path traversal protection.

Types

type Cache

type Cache struct {
	FnByID     map[string]*FuncInfo
	IDToPath   map[string]string
	Callers    map[string][]CallerRef // fnID → callers
	Callees    map[string][]CallerRef // fnID → callees
	Imports    map[string][]string    // filePath → imported paths
	Importers  map[string][]string    // filePath → importer paths
	FileDomain map[string]string      // filePath → domain name
}

Cache holds the indexed graph data.

func NewCache

func NewCache() *Cache

NewCache creates an empty Cache.

func (*Cache) Build

func (c *Cache) Build(ir *api.ShardIR)

Build populates the cache from a ShardIR result. ShardIR preserves the full Node/Relationship data (IDs, labels, properties) required for shard rendering.

func (*Cache) FuncName

func (c *Cache) FuncName(fnID string) string

FuncName returns the short name for a function ID.

func (*Cache) SourceFiles

func (c *Cache) SourceFiles() []string

SourceFiles returns all source file paths known to the graph.

func (*Cache) TransitiveDependents

func (c *Cache) TransitiveDependents(filePath string) map[string]bool

TransitiveDependents returns all files transitively importing the given file.

type CallerRef

type CallerRef struct {
	FuncID string
	File   string
	Line   int
}

CallerRef is a reference to a calling/called function.

type Daemon

type Daemon struct {
	// contains filtered or unexported fields
}

Daemon watches for file changes and keeps shards fresh.

func NewDaemon

func NewDaemon(cfg DaemonConfig, client *api.Client) *Daemon

NewDaemon creates a daemon with the given config and API client.

func (*Daemon) Run

func (d *Daemon) Run(ctx context.Context) error

Run starts the daemon. Blocks until context is cancelled. Loads existing cache if available, otherwise does a full generate. Then waits for triggers (UDP and/or fs-watch) to perform incremental updates.

type DaemonConfig

type DaemonConfig struct {
	RepoDir      string
	CacheFile    string
	Debounce     time.Duration
	NotifyPort   int
	FSWatch      bool
	PollInterval time.Duration
	LogFunc      func(string, ...interface{})
	// OnReady is called once after the initial generate completes.
	OnReady func(GraphStats)
	// OnSyncing is called when an incremental API call starts, before the
	// response arrives. n is the number of changed files being processed.
	OnSyncing func(n int)
	// OnUpdate is called after each incremental update completes.
	OnUpdate func(GraphStats)
}

DaemonConfig holds watch daemon configuration.

type FuncInfo

type FuncInfo struct {
	ID     string
	Name   string
	File   string
	Line   int
	Domain string
}

FuncInfo holds metadata about a function node.

type GenerateOptions

type GenerateOptions struct {
	Force     bool
	DryRun    bool
	CacheFile string
}

GenerateOptions configures the generate command.

type GraphStats

type GraphStats struct {
	SourceFiles       int
	Functions         int
	Relationships     int
	DeadFunctionCount int  // functions with no callers (proxy for unreachable code)
	FromCache         bool // true when data was loaded from a local cache
}

GraphStats summarises what was mapped after a generate or incremental update.

type LangStat

type LangStat struct {
	Ext   string
	Count int
}

LangStat holds a file count for a single file extension.

func LanguageStats

func LanguageStats(files []string) []LangStat

LanguageStats counts files by extension (without leading dot), sorted by count descending. Only non-empty extensions are included; at most 10 are returned.

type RenderOptions

type RenderOptions struct {
	CacheFile string
	DryRun    bool
}

RenderOptions configures the render command.

type WatchEvent

type WatchEvent struct {
	Path string
	Time time.Time
}

WatchEvent represents a detected file change.

type WatchOptions

type WatchOptions struct {
	CacheFile    string
	Debounce     time.Duration
	NotifyPort   int
	FSWatch      bool
	PollInterval time.Duration
}

WatchOptions configures the watch command.

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

Watcher detects source file changes using git as the source of truth.

func NewWatcher

func NewWatcher(repoDir string, pollInterval time.Duration) *Watcher

NewWatcher creates a watcher for the given repo directory.

func (*Watcher) Events

func (w *Watcher) Events() <-chan []WatchEvent

Events returns the channel that receives batches of change events.

func (*Watcher) Run

func (w *Watcher) Run(ctx context.Context)

Run starts the watcher loop. It blocks until the context is cancelled.