scanner

Documentation

Overview

Package scanner walks a profile's JSONL session files and emits parsed contracts.Events. It is defensive: unknown event types and malformed lines are logged and skipped, never panicked on. File-level concurrency is bounded by a worker pool sized to runtime.NumCPU(). Incremental scanning is driven by an injectable CursorStore so unit tests can use an in-memory map while Phase 2 backs it with internal/storage.

Index

• Constants
• type AttributedEvent
• type Cursor
• type CursorStore
  • func NewMemoryCursorStore() CursorStore
• type Scanner
  • func NewScanner(cs CursorStore) *Scanner
  • func (s *Scanner) Scan(ctx context.Context, profile contracts.Profile) (<-chan contracts.Event, <-chan error)
  • func (s *Scanner) ScanShared(ctx context.Context, projectsRoot string, lookup SessionLookup) (events <-chan AttributedEvent, errs <-chan error)
• type SessionLookup

Constants

const SharedCursorProfile = "__shared__"

SharedCursorProfile is the profile-name sentinel used for scan cursors that belong to the shared-projects scan path rather than to one ccx profile.

Types

type AttributedEvent

type AttributedEvent struct {
	Event   contracts.Event
	Profile string
}

AttributedEvent is an Event plus the ccx profile that owns its Claude Code session.

type Cursor

type Cursor struct {
	Offset int64
	Inode  uint64
}

Cursor is the per-file position checkpoint used for incremental scanning. Offset is the next byte to read; Inode is the underlying file inode at the time the offset was recorded. If the inode changes on a subsequent scan, the file is assumed to have been rotated or replaced and the scan restarts from offset 0.

type CursorStore

type CursorStore interface {
	// Get returns the saved cursor for (profile, file). If absent, returns
	// the zero-value Cursor and a nil error.
	Get(ctx context.Context, profile, file string) (Cursor, error)
	// Set persists the cursor for (profile, file).
	Set(ctx context.Context, profile, file string, c Cursor) error
}

CursorStore persists per-file scan checkpoints. In Phase 2 it is backed by internal/storage; unit tests use NewMemoryCursorStore.

func NewMemoryCursorStore

func NewMemoryCursorStore() CursorStore

NewMemoryCursorStore returns a CursorStore backed by a sync-protected map. Suitable for unit tests and short-lived processes; not durable.

type Scanner

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

Scanner implements contracts.Scanner. Create with NewScanner.

func NewScanner

func NewScanner(cs CursorStore) *Scanner

NewScanner constructs a Scanner using the given CursorStore. The worker pool size defaults to runtime.NumCPU() (minimum 1). The logger defaults to slog.Default().

func (*Scanner) Scan

func (s *Scanner) Scan(ctx context.Context, profile contracts.Profile) (<-chan contracts.Event, <-chan error)

Scan walks <profile.ConfigDir>/projects/*/<session-uuid>.jsonl and emits parsed Events on the returned channel. The events channel is closed when scanning completes or ctx is cancelled. The errs channel reports fatal errors (e.g., directory traversal failures); it is also closed when done. Per-line parse failures are logged and skipped, not reported on errs.

func (*Scanner) ScanShared

func (s *Scanner) ScanShared(ctx context.Context, projectsRoot string, lookup SessionLookup) (events <-chan AttributedEvent, errs <-chan error)

ScanShared walks a shared projects root once and emits events attributed to their owning ccx profile via lookup.

type SessionLookup

type SessionLookup interface {
	ProfileForSession(ctx context.Context, sessionID string) (profile string, ok bool, err error)
}

SessionLookup resolves Claude Code session IDs to the owning ccx profile.