Documentation
¶
Index ¶
- Constants
- Variables
- func BuildCacheKey(in CacheKeyInputs) (string, bool)
- func DetectCommands(ctx context.Context, claude *anthropic.Client, workDir string) ([]config.Command, error)
- func ExpandCommand(workDir, command string) string
- func HooksDisabled(workDir string, envDisabled bool) bool
- func List(cfg *config.ProjectConfig, status iostream.StatusFunc) error
- func NewHookExitError(code int) error
- func ReadAttempts(sessionID string) int
- func ResetAttempts(sessionID string)
- func RunDryRun(cfg *config.ProjectConfig, name string, status iostream.StatusFunc) error
- func TestSuitesTemplate(workDir string) string
- func TrackFailedAttempt(sessionID string, warn io.Writer) int
- func WorkspaceExists(ctx context.Context, ...) error
- func WrapHookResult(sessionID string, execErr error, maxAttempts int, warn io.Writer) error
- type CacheKeyInputs
- type CachedResult
- type HookExitError
- type PackageManager
- type Result
- func RunAll(ctx context.Context, workDir string, cfg *config.ProjectConfig, ...) (Result, error)
- func RunInline(ctx context.Context, workDir, name, command string, status iostream.StatusFunc, ...) (Result, error)
- func RunNamed(ctx context.Context, workDir, name string, cfg *config.ProjectConfig, ...) (Result, error)
- func RunRemote(ctx context.Context, ...) (Result, error)
- func RunRemoteInline(ctx context.Context, ...) (Result, error)
Constants ¶
const DefaultMaxAttempts = 3
DefaultMaxAttempts is the default number of consecutive Stop hook re-signals before chunk gives up and tells the agent to ask the user for help.
const DefaultTimeout = 300
DefaultTimeout is the per-command execution timeout in seconds.
Variables ¶
var ErrNotConfigured = errors.New("no validate commands configured")
ErrNotConfigured indicates no validate commands are configured.
var ErrWorkspaceNotFound = errors.New("workspace directory not found on sidecar")
ErrWorkspaceNotFound is returned when the remote workspace directory does not exist.
Functions ¶
func BuildCacheKey ¶ added in v0.7.144
func BuildCacheKey(in CacheKeyInputs) (string, bool)
BuildCacheKey constructs the cache key for a validate run from the working-tree fingerprint, the serialized project config, and the execution target.
The second return value is false when the fingerprint is the zero Worktree — gitutil.Fingerprint could not establish the tree's state — or the config cannot be serialized. Callers must not read or write the cache in that case: with no trustworthy git state the key would depend only on the config and would therefore stay stable across code changes, turning every subsequent run into a false cache hit.
func DetectCommands ¶ added in v0.7.2
func DetectCommands(ctx context.Context, claude *anthropic.Client, workDir string) ([]config.Command, error)
DetectCommands returns the full set of validate commands for the repo with metadata. For known toolchains it returns richer commands without calling Claude. Claude is only used as a fallback for unknown toolchains, and only when a client is provided.
func ExpandCommand ¶ added in v0.7.147
ExpandCommand replaces template variables in command before execution. {{CHANGED_PACKAGES}} expands to the space-separated list of Go package paths whose source files appear in `git diff HEAD`. Expands to "./..." when no .go files changed.
Exported because every path that ships a configured command somewhere else to run must expand it first. Skipping expansion does not fail loudly: the literal {{CHANGED_PACKAGES}} reaches the shell, which exits non-zero for a reason that has nothing to do with the code under test.
func HooksDisabled ¶ added in v0.7.51
HooksDisabled reports whether chunk validate hooks are currently suppressed. envDisabled should be set by the caller from CHUNK_HOOKS_DISABLED; it returns true when that flag is set or the sentinel file .chunk/hooks-disabled exists under workDir. On any error other than ErrNotExist the function fails open (returns false) so hooks continue to run when the check is uncertain.
func List ¶
func List(cfg *config.ProjectConfig, status iostream.StatusFunc) error
List prints all configured command names and their run strings, tagged with where each one runs and any role that decides it. Without the tags there is no way to see which commands `chunk validate --mark-remote` would change.
func NewHookExitError ¶ added in v0.7.51
NewHookExitError returns a HookExitError with the given exit code.
func ReadAttempts ¶ added in v0.7.143
ReadAttempts returns the current failure count for the given session without modifying it. Returns 0 when no state file exists.
func ResetAttempts ¶ added in v0.7.31
func ResetAttempts(sessionID string)
ResetAttempts clears the failure counter for the given session.
func RunDryRun ¶
func RunDryRun(cfg *config.ProjectConfig, name string, status iostream.StatusFunc) error
RunDryRun prints commands without executing them.
func TestSuitesTemplate ¶ added in v0.7.52
TestSuitesTemplate returns the contents of .circleci/test-suites.yml for the detected toolchain in workDir, or "" if no toolchain template applies.
The returned YAML targets CircleCI Smarter Testing: `<< test.atoms >>` is substituted at run time with the subset of test atoms picked by the platform.
func TrackFailedAttempt ¶ added in v0.7.31
TrackFailedAttempt increments the failure counter for the given session and returns the new count. warn is an optional writer for diagnostic messages (pass nil to suppress).
func WorkspaceExists ¶ added in v0.7.49
func WorkspaceExists(ctx context.Context, execFn func(context.Context, string) (string, string, int, error), dest string) error
WorkspaceExists checks whether dest exists as a directory on the remote sidecar.
func WrapHookResult ¶ added in v0.7.31
WrapHookResult applies Stop hook lifecycle to the result of running validate commands. On success it resets the attempt counter. On failure it increments the counter and returns a HookExitError with code 2 to re-signal the agent, or prints a give-up message and returns nil once maxAttempts is reached.
Types ¶
type CacheKeyInputs ¶ added in v0.7.144
type CacheKeyInputs struct {
// Worktree fingerprints the tree the run will validate.
Worktree gitutil.Worktree
// CommandName is the single command being run, or "" when all commands run.
CommandName string
// Config is the project config driving the run, hashed whole. The commands
// are the obvious input, but the environment block decides what those
// commands run against, and a project that gitignores .chunk/ gets no
// invalidation from the working-tree digest when any of it changes.
Config *config.ProjectConfig
// Target identifies where the commands execute: "" for a local run,
// otherwise an opaque description of the sidecar. Sidecar routing depends on
// mutable state outside the repo, so it has to participate in the key — a
// working tree validated against one sidecar says nothing about another.
Target string
}
CacheKeyInputs collects the working-tree fingerprint plus everything outside the tree that can change the outcome of a validate run.
type CachedResult ¶
CachedResult records the timestamp of a successful validate run. Only successful runs are cached; failures are never stored so the agent always retries after a fix, even when the working tree has not changed.
CachedAt is a debugging breadcrumb: presence of the entry is what marks a run as successful, and expiry works off the entry file's modification time, which records the same instant. It is here so a cache directory can be read by eye.
type HookExitError ¶ added in v0.7.31
type HookExitError struct {
// contains filtered or unexported fields
}
HookExitError signals a specific process exit code without printing additional error output. All output must be written before this error is returned.
func (*HookExitError) Error ¶ added in v0.7.31
func (e *HookExitError) Error() string
func (*HookExitError) ExitCode ¶ added in v0.7.31
func (e *HookExitError) ExitCode() int
type PackageManager ¶ added in v0.7.2
PackageManager holds the name and CI-safe install command for a detected package manager.
func DetectPackageManager ¶ added in v0.7.2
func DetectPackageManager(workDir string) *PackageManager
DetectPackageManager returns the detected package manager and its CI-safe install command, or nil.
type Result ¶ added in v0.7.151
Result holds the pass/fail counts from a validate run.
func RunAll ¶
func RunAll(ctx context.Context, workDir string, cfg *config.ProjectConfig, status iostream.StatusFunc, streams iostream.Streams) (Result, error)
RunAll runs all configured commands, stopping at the first failure.
func RunInline ¶
func RunInline(ctx context.Context, workDir, name, command string, status iostream.StatusFunc, streams iostream.Streams) (Result, error)
RunInline runs an inline command string.
func RunNamed ¶
func RunNamed(ctx context.Context, workDir, name string, cfg *config.ProjectConfig, status iostream.StatusFunc, streams iostream.Streams) (Result, error)
RunNamed runs a single named command from config.
func RunRemote ¶
func RunRemote(ctx context.Context, execFn func(ctx context.Context, script string) (stdout, stderr string, exitCode int, err error), cfg *config.ProjectConfig, name, dest, workDir string, status iostream.StatusFunc, streams iostream.Streams) (Result, error)
RunRemote runs commands on a remote sidecar via SSH. If name is non-empty, only the named command is run. workDir is the local repository root used to expand {{CHANGED_PACKAGES}}.
func RunRemoteInline ¶ added in v0.7.29
func RunRemoteInline(ctx context.Context, execFn func(ctx context.Context, script string) (stdout, stderr string, exitCode int, err error), name, command, dest string, status iostream.StatusFunc, streams iostream.Streams) (Result, error)
RunRemoteInline runs a single inline command on a remote sidecar via SSH.
Source Files