explain

Documentation

Overview

Package explain implements the backing engine for the `semantica skills explain` command. The layered fallback runs local lineage data first, then the workspace API for connected repos, then a redacted git diff when neither has a record.

The contract: callers always get a structured Output back when the engine could decide what to say. Errors from this package are reserved for genuine command-runtime failures (CLI bug, missing git binary, etc.), so SKILL.md bodies can rely on a single rule: non-zero exit means "something broke, print stderr"; zero exit means "parse the JSON and render per the mode field".

Index

• Constants
• func IsSafeRef(ref string) bool
• type CommitMetadata
• type FallbackReason
• type Input
• type Mode
• type Output
• type Service
  • func NewService() *Service
  • func (s *Service) Explain(ctx context.Context, in Input) (*Output, error)

Constants

const (
	ReasonRedactionFailed  = "redaction_failed"
	ReasonRefNotResolvable = "ref_not_resolvable"
	ReasonRefUnsafe        = "ref_unsafe"
)

Stable reason values for blocked / not-found responses. Existing values do not change shape; adding values is a non-breaking change.

const MaxDiffBytes = 12_000

MaxDiffBytes caps the redacted diff_excerpt length so the JSON payload stays small. Matches the bound auto-playbook uses for similar bounded views.

Order matters: the bound is applied AFTER redaction, never before. If we truncated the raw diff first, a secret that straddled the boundary would reach the redactor as a partial fragment that the gitleaks regexes might miss, leaking the pre-cutoff portion into the agent's response. Redacting the whole diff first guarantees every secret token is matched against complete content; only redaction-safe bytes (literal markdown plus [REDACTED] tokens) are then truncated.

Functions

func IsSafeRef

func IsSafeRef(ref string) bool

IsSafeRef reports whether ref matches one of the three accepted shapes: HEAD, a commit SHA, or a simple branch / tag name. The CLI also runs `git rev-parse --verify` on safe refs; the static check up front avoids spawning git for input we already know to reject.

Path-shaped inputs (leading `/`, `..` traversal) and shell-meta characters are rejected here, before anything reaches git.

Types

type CommitMetadata

type CommitMetadata struct {
	Hash    string `json:"hash"`
	Author  string `json:"author"`
	Date    string `json:"date"`
	Subject string `json:"subject"`
}

CommitMetadata is the shape returned in git-only mode so the agent can render the commit header without re-running git.

type FallbackReason

type FallbackReason string

FallbackReason explains why the engine produced a git-only summary instead of provenance. The git-only path emits remote_not_attempted; API-backed modes can use the other values.

const (
	FallbackNotInRemote        FallbackReason = "not_in_remote"
	FallbackRemoteUnavailable  FallbackReason = "remote_unavailable"
	FallbackRemoteNotAttempted FallbackReason = "remote_not_attempted"
)

type Input

type Input struct {
	RepoPath string
	Ref      string
}

Input narrows the surface callers must provide.

type Mode

type Mode string

Mode is the top-level dispatcher in the JSON contract. The skill body switches on it to render the right shape.

const (
	ModeProvenance Mode = "provenance"
	ModeGitOnly    Mode = "git-only"
	ModeBlocked    Mode = "blocked"
	ModeNotFound   Mode = "not-found"
)

type Output

type Output struct {
	Mode           Mode            `json:"mode"`
	HumanText      string          `json:"human_text,omitempty"`
	CommitMetadata *CommitMetadata `json:"commit_metadata,omitempty"`
	DiffExcerpt    string          `json:"diff_excerpt,omitempty"`
	FallbackReason FallbackReason  `json:"fallback_reason,omitempty"`
	Reason         string          `json:"reason,omitempty"`
	Message        string          `json:"message,omitempty"`
}

Output is the JSON contract the SKILL.md body parses. Field tags use omitempty so each mode produces a clean, mode-shaped object without empty-string noise the agent might accidentally render.

type Service

type Service struct{}

Service runs the layered fallback. Construct via NewService.

func NewService

func NewService() *Service

NewService returns a stateless service.

func (*Service) Explain

func (s *Service) Explain(ctx context.Context, in Input) (*Output, error)

Explain resolves the requested ref and returns the best available explanation shape, walking the layered fallback in order:

1. Local lineage.db - captured prompts and attribution data on this machine.
2. Remote API - workspace playbooks for commits another teammate's CLI uploaded.
3. Git-only - bounded, redacted diff with a fallback_reason that tells the SKILL.md body why the upper layers did not produce content.