Documentation
¶
Overview ¶
Package instrument turns "the agent instruments your app" from a pasted prompt into a real capability. It reads a repository, detects the framework, finds where the tracking snippet belongs, and locates the call-sites that deserve a custom event (signup, login, checkout, activate) — returning a structured Proposal of exact {event, file, line, track() snippet, properties} edits.
smolanalytics never writes the user's code itself. The coding agent (Cursor / Claude Code) calls Propose over MCP, gets these deterministic, diffable edits, and applies them with its own editor — guided by us, correct by construction. The same engine backs the `smolanalytics instrument` CLI for people who want one command instead of an agent. Deterministic and dependency-free: no model call, so it is re-runnable and its output can be diff-reviewed.
Index ¶
- func FindAllTracked(root string) map[string]TrackedEvent
- func ProposeResult(root, host, key string) map[string]any
- func SuggestFixResult(root, event string) map[string]any
- func Wired(root string, names []string) map[string]TrackedEvent
- type CallSite
- type Framework
- type Proposal
- type SnippetProposal
- type TrackedEvent
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindAllTracked ¶
func FindAllTracked(root string) map[string]TrackedEvent
FindAllTracked scans the repo for every smolanalytics.track("name") call and returns each event name -> where it was first found. Backs `plan sync`: regenerate the tracking plan from the code that actually implements it, so the two can't drift.
func ProposeResult ¶
ProposeResult is the full propose_instrumentation payload. Both the MCP tool and the cloud stdio proxy return this, so the two surfaces cannot drift.
func SuggestFixResult ¶
SuggestFixResult is the suggest_instrumentation_fix payload: the call-site(s) for one event and the exact snippet to add there.
func Wired ¶
func Wired(root string, names []string) map[string]TrackedEvent
Wired scans the repo for each of the given event names and returns where it is already instrumented — a smolanalytics.track("name") call, or a name field on a line that also mentions /v1/events. It lets the verify loop distinguish "wired but not yet fired" from "not wired at all", and backs the code-side drift gate. Deterministic, no model.
Types ¶
type CallSite ¶
type CallSite struct {
Event string `json:"event"`
File string `json:"file"` // repo-relative
Line int `json:"line"`
Context string `json:"context"` // the matched source line, trimmed
Snippet string `json:"snippet"` // the exact track() / POST call to add near this line
Properties []string `json:"properties"`
Confidence string `json:"confidence"` // high | medium
}
CallSite is one place the app does something worth a named event, plus the exact track() call to insert there.
func ScanCallSites ¶
ScanCallSites walks the repo and returns the call-sites that look like a custom event, deduped so the same event doesn't flood the list, capped for a readable proposal.
type Framework ¶
type Framework struct {
Name string `json:"name"` // next-app, next-pages, react, vue, svelte, express, rails, django, flask, laravel, go, static, unknown
Language string `json:"language"` // typescript, javascript, python, ruby, php, go, html
Install string `json:"install"` // human note: exactly where the snippet goes
SnippetFile string `json:"snippet_file"` // best-guess file to insert the snippet into ("" if none found)
}
Framework is the detected stack, and where/how the base snippet is installed.
func DetectFramework ¶
DetectFramework inspects the repo's manifests to name the stack and pick the file the base snippet belongs in.
type Proposal ¶
type Proposal struct {
Framework Framework `json:"framework"`
Snippet SnippetProposal `json:"snippet"`
Events []CallSite `json:"events"`
Notes []string `json:"notes"`
}
Proposal is the whole instrumentation plan for a repo: the base snippet, the custom events found, and the tracking-plan the agent should declare.
func Propose ¶
Propose is the whole engine: detect the stack, build the base snippet with the real host+key, scan for custom events, and assemble the tracking-plan advice.
func (Proposal) PlanEvents ¶
PlanEvents distills a proposal into the distinct tracking-plan events to declare (deduped by name), so the CLI and the agent write the same plan the code implements.
type SnippetProposal ¶
type SnippetProposal struct {
File string `json:"file"` // where to put it ("" → paste into the site's <head>)
Code string `json:"code"` // the exact snippet, host + key already resolved
Note string `json:"note"`
}
SnippetProposal is the base install (autocapture) snippet and where it belongs.
type TrackedEvent ¶
type TrackedEvent struct {
Name string `json:"name"`
File string `json:"file"`
Line int `json:"line"`
}
TrackedEvent is an event name found already wired in the code, and where.
Source Files