util

Documentation

Index

• Constants
• func AppConfigDir() (string, error)
• func AppendActivityLog(semDir, format string, args ...any)
• func AppendHookError(provider, hook, msg string)
• func CommitAttributionSummaryPath(semDir string) string
• func EnsureGitignoreEntries(repoRoot string, entries []string) error
• func HookErrorLogPath() (string, error)
• func IsConnected(semDir string) bool
• func IsEnabled(semDir string) bool
• func IsEnabledAt(repoPath string) bool
• func IsPlaybookEnabled(semDir string) bool
• func OpenWorkerLog(semDir string) (*os.File, error)
• func PreCommitCheckpointPath(semDir string) string
• func ResolveExecutable(names []string, extraCandidates ...string) string
• func SettingsPath(semDir string) string
• func ShortID(full string) string
• func TrailersEnabled(semDir string) bool
• func WriteSettings(semDir string, s Settings) error
• type Automations
• type HookErrorEntry
  • func ReadHookErrorTail(maxLines int) ([]HookErrorEntry, error)
• type PlaybookAutomation
• type Settings
  • func ReadSettings(semDir string) (Settings, error)

Constants

const CommitAttributionSummaryFile = ".commit-attribution-summary"

const HookErrorLogBasename = "hook-errors.log"

HookErrorLogBasename is the filename used for the global capture sidecar log. Hooks themselves remain non-blocking (`|| true` is preserved); this file gives doctor a place to read failures that would otherwise be silent.

const PreCommitCheckpointFile = ".pre-commit-checkpoint"

const ShortIDLen = 8

ShortIDLen is the number of characters shown in human-facing checkpoint IDs.

Functions

func AppConfigDir

func AppConfigDir() (string, error)

AppConfigDir returns the global Semantica config directory.

func AppendActivityLog

func AppendActivityLog(semDir, format string, args ...any)

AppendActivityLog appends a timestamped log line to .semantica/activity.log.

func AppendHookError

func AppendHookError(provider, hook, msg string)

AppendHookError writes a JSONL entry to the global sidecar log at <AppConfigDir>/hook-errors.log. Write failures are ignored so diagnostics never block provider hooks.

The log directory is auto-created. Provider and hook may be empty for failures that do not have that context (e.g. unknown provider).

func CommitAttributionSummaryPath

func CommitAttributionSummaryPath(semDir string) string

func EnsureGitignoreEntries

func EnsureGitignoreEntries(repoRoot string, entries []string) error

EnsureGitignoreEntries appends any missing entries to the repo's .gitignore under a "# Semantica" section. Entries that already appear (with or without trailing slash for directories) are skipped.

func HookErrorLogPath

func HookErrorLogPath() (string, error)

HookErrorLogPath exposes the sidecar log location for diagnostic messages.

func IsConnected

func IsConnected(semDir string) bool

IsConnected returns true if the repo is connected to Semantica.

func IsEnabled

func IsEnabled(semDir string) bool

IsEnabled checks whether Semantica is enabled by looking for the marker file (.semantica/enabled) rather than parsing settings.json.

func IsEnabledAt

func IsEnabledAt(repoPath string) bool

IsEnabledAt checks whether Semantica is enabled for a repo at the given path.

func IsPlaybookEnabled

func IsPlaybookEnabled(semDir string) bool

IsPlaybookEnabled returns true if the auto-playbook automation is enabled.

func OpenWorkerLog

func OpenWorkerLog(semDir string) (*os.File, error)

OpenWorkerLog opens .semantica/worker.log in append mode. The caller is responsible for closing the returned file.

func PreCommitCheckpointPath

func PreCommitCheckpointPath(semDir string) string

func ResolveExecutable

func ResolveExecutable(names []string, extraCandidates ...string) string

ResolveExecutable returns the first matching executable path for any of the provided binary names. It checks PATH first, then common user and package manager install locations used across the supported platforms.

func SettingsPath

func SettingsPath(semDir string) string

func ShortID

func ShortID(full string) string

ShortID returns the first ShortIDLen characters of a full ID. If the input is shorter than ShortIDLen, it is returned unchanged.

func TrailersEnabled

func TrailersEnabled(semDir string) bool

TrailersEnabled returns whether attribution and diagnostics trailers are on. Defaults to true when the key is absent or settings cannot be read.

func WriteSettings

func WriteSettings(semDir string, s Settings) error

WriteSettings atomically writes the settings file via tmp+rename. It also maintains a .semantica/enabled marker file used by Git hooks for a reliable enabled check without parsing JSON in shell.

Types

type Automations

type Automations struct {
	Playbook PlaybookAutomation `json:"playbook"`
}

type HookErrorEntry

type HookErrorEntry struct {
	Timestamp string `json:"ts"`
	Provider  string `json:"provider,omitempty"`
	Hook      string `json:"hook,omitempty"`
	Message   string `json:"msg"`
}

HookErrorEntry is the JSONL shape doctor consumes when grouping hook errors by provider/hook.

func ReadHookErrorTail

func ReadHookErrorTail(maxLines int) ([]HookErrorEntry, error)

ReadHookErrorTail reads up to maxLines most-recent JSONL entries from the hook-errors.log. Malformed or truncated lines are silently skipped so a partially-written record near the end of the file does not break diagnostics.

type PlaybookAutomation

type PlaybookAutomation struct {
	Enabled bool `json:"enabled"`
}

type Settings

type Settings struct {
	Enabled         bool         `json:"enabled"`
	Version         int          `json:"version"`
	Providers       []string     `json:"providers,omitempty"`
	Trailers        *bool        `json:"trailers,omitempty"`
	Automations     *Automations `json:"automations,omitempty"`
	Connected       bool         `json:"connected"`
	ConnectedRepoID string       `json:"connected_repo_id,omitempty"`
}

func ReadSettings

func ReadSettings(semDir string) (Settings, error)

ReadSettings reads the settings file from the given .semantica directory. Returns zero-value Settings (Enabled: false) if the file is missing. Returns an error if the file exists but cannot be parsed, so callers can distinguish "not configured" from "settings format has changed."