Documentation
¶
Overview ¶
Package fuzzy is the offline catalog fuzz harness for ingest and mv invariants. It is not linked into the rft CLI binary; drive it via go test or fuzzy.Run.
Catalog: testdata/fuzzy/projects.toml (real-world pins, setup/check, mv grains).
Run:
mise run fuzzy:prefetch // warm work-root (network) mise run fuzzy:run // unit + local; catalog seeds skip if cold go test ./internal/fuzzy // same package; plain go test uses a private temp work-root
With FUZZTIME set, fuzzy:run drives TestCatalogFuzzCampaign (catalog RNG stress). After prefetch, Offline:true runs use only the work-root cache.
Index ¶
- Constants
- Variables
- func ApplyMvPlan(root string, plan movePlan) ([]ingest.Edit, error)
- func ApplyProjectMise(p Project, projectRoot string) error
- func CheckAllowed(allow, noIsolate bool) error
- func CheckArgv(p Project) []string
- func DefaultCatalogPath() string
- func DefaultWorkRoot() string
- func EnsureImages(refs []string, pull bool) error
- func ForceRemoveAll(path string) error
- func HasEmbeddedMise(p Project) bool
- func ImageKey(p Project, commit string) string
- func ImagePresent(ref string) bool
- func ModuleRoot() string
- func MuteProcessLogs() (restore func())
- func OfflineSessionEnv() map[string]string
- func Prefetch(ctx context.Context, opts PrefetchOptions) (workRoot string, err error)
- func PrefetchOnce(ctx context.Context) (workRoot string, err error)
- func ProjectRoot(workDir string, p Project) string
- func RequireDocker(ctx context.Context) error
- func RequiredImages(projects []Project) []string
- func ResolveIngestRoot(workDir string, rel string) string
- func ResolveMiseTOML(p Project) (string, error)
- func RunIngestProject(p Project, workDir string, opts InvariantOptions, report *Report, out *Result) error
- func ScaffoldAttempt(workRoot, destDir string, res MvAttemptResult) error
- func ScaffoldMvFixture(workRoot, destDir, source, destination string, edits []ingest.Edit) error
- func SetDefaultWorkRoot(root string)
- func SetupArgv(p Project) []string
- func SharedWorkRoot() string
- func ValidateOfflineReady(ws *Workspace, projects []Project, noIsolate bool) error
- func WorkRootPinnedByEnv() bool
- type CatalogCanvas
- type Event
- type Grain
- type GuardError
- type InvariantFailure
- func CheckIdempotentIngest(dir string, first *ingest.Result) []InvariantFailure
- func CheckInvariants(dir string, result *ingest.Result, opts InvariantOptions) []InvariantFailure
- func CheckWalkSymbolsSubset(dir string, result *ingest.Result) []InvariantFailure
- func RunIngestOnRoot(root string, opts InvariantOptions) (result *ingest.Result, fails []InvariantFailure, err error)
- type InvariantOptions
- type IsolateConfig
- type Manifest
- type ManifestProject
- type Meta
- type Mode
- type MoveNode
- type MvAttemptResult
- type MvConfig
- type MvRunOptions
- type Options
- type Placement
- type PlanInput
- type PrefetchOptions
- type PrepareOptions
- type Project
- type Report
- func (r *Report) Close() error
- func (r *Report) LogEvent(ev Event) error
- func (r *Report) LogPath(rel string) string
- func (r *Report) ScaffoldDir(projectID string, seed int64, iter int) string
- func (r *Report) WriteLog(name, content string) error
- func (r *Report) WriteRunResult(name string, res RunResult) (string, error)
- type Result
- type RunResult
- type Runner
- type Session
- type Workspace
- func (w *Workspace) BuildManifest(projects []Project, noIsolate bool, commits map[string]string) Manifest
- func (w *Workspace) HasPreserveSnapshot(p Project) bool
- func (w *Workspace) LoadManifest() (*Manifest, error)
- func (w *Workspace) MiseDataRoot() string
- func (w *Workspace) Prepare(p Project, runID string, opts PrepareOptions) (workDir string, commit string, err error)
- func (w *Workspace) ReportsDir() string
- func (w *Workspace) Reset(p Project, workDir string) error
- func (w *Workspace) RestorePreserveSnapshot(p Project, workDir string) error
- func (w *Workspace) SaveManifest(m Manifest) error
- func (w *Workspace) SavePreserveSnapshot(p Project, workDir string) error
Constants ¶
const CleanupImage = DefaultMiseImage
CleanupImage is used for privileged host cleanup (ForceRemoveAll). Same pin as the session image so prefetch only needs one docker pull.
const DefaultMiseImage = "jdxcode/mise@sha256:d536ef04425b3321dcbd60f6e7687994d5a1b8859574f0f9c2529dba620b74cb"
DefaultMiseImage is the pinned testcontainers image (digest, not a floating tag).
const IngestRunID = "ingest"
IngestRunID is the stable worktree name used by ingest-only runs so reruns reuse state.
const OfflineEnvKey = "RFT_FUZZY_OFFLINE"
OfflineEnvKey is set in isolate sessions when --offline is active. Catalog setup tasks may branch on it (e.g. uv/pnpm/mvn offline flags).
const PrefetchRunID = "prefetch"
PrefetchRunID is the stable worktree name used by prefetch so reruns reuse state.
Variables ¶
var DefaultCatalog []Project
DefaultCatalog is testdata/fuzzy/projects.toml, loaded once at package init (sorted by slug). Tests and harness defaults read from here; use LoadCatalog only for alternate paths (temp fixtures, filters).
Functions ¶
func ApplyMvPlan ¶
ApplyMvPlan runs Rename+ApplyPlan and returns text edits from the plan.
func ApplyProjectMise ¶
ApplyProjectMise writes [projects.<slug>.mise] as mise.toml in the project root. An existing mise.toml is moved aside to mise.toml.refactree-upstream once.
func CheckAllowed ¶
CheckAllowed enforces a host-safety policy only when isolation is disabled. With testcontainers (default), untrusted setup/check run inside Docker, so an ephemeral host is not required.
func DefaultCatalogPath ¶
func DefaultCatalogPath() string
DefaultCatalogPath resolves testdata/fuzzy/projects.toml from cwd or module root.
func DefaultWorkRoot ¶
func DefaultWorkRoot() string
DefaultWorkRoot is the process work-root for the fuzzy harness: cache/, preserve/, runs/, mise-data/, reports/. Fixed at init (or last SetDefaultWorkRoot); not re-read from the env on each call.
func EnsureImages ¶
EnsureImages makes sure each image ref is available locally. When pull is true, missing images are docker-pulled (progress streamed live). When pull is false (offline), missing images return an error pointing at prefetch.
func ForceRemoveAll ¶
ForceRemoveAll deletes path, using a privileged docker rm when the host user cannot remove root-owned artifacts left by older isolation runs.
func HasEmbeddedMise ¶
HasEmbeddedMise reports whether the project supplies a [projects.<slug>.mise] table.
func ImagePresent ¶
ImagePresent reports whether the local docker daemon has ref.
func ModuleRoot ¶
func ModuleRoot() string
ModuleRoot attempts to find the repo root containing testdata/fuzzy.
func MuteProcessLogs ¶
func MuteProcessLogs() (restore func())
MuteProcessLogs disables teeing to os.Stdout/os.Stderr (fuzz workers). Returns a restore function.
func OfflineSessionEnv ¶
OfflineSessionEnv returns env vars for package managers and mise when offline.
func Prefetch ¶
func Prefetch(ctx context.Context, opts PrefetchOptions) (workRoot string, err error)
Prefetch fills gaps in work-root or no-ops when already warm. Concurrent calls for the same process are serialized on a process-wide lock (one warm at a time).
func PrefetchOnce ¶
PrefetchOnce ensures DefaultWorkRoot has everything needed for offline catalog runs, then returns that path.
Behaviour:
- If the work-root is already warm for the selected projects (manifest, git pins, preserve snapshots, mise-data, local docker images when isolating), this is a no-op and returns immediately.
- Otherwise it runs ModePrefetch, which skips individual projects that are already warm and only downloads/setup what is missing.
Safe for concurrent callers (mutex). Unlike sync.Once, a failed attempt does not permanently block later retries in the same process.
Env:
RFT_FUZZY_WORK_ROOT durable work-root
RFT_FUZZY_NO_ISOLATE=1 host setup/check (no Docker)
RFT_FUZZY_PROJECT comma-separated project slugs (default: all catalog;
also filters NewCatalogCanvas / catalog campaigns)
func ProjectRoot ¶
ProjectRoot joins workspace dir with the project's root subdir.
func RequireDocker ¶
RequireDocker checks that the Docker API is reachable (Jules includes docker).
func RequiredImages ¶
RequiredImages returns the unique docker image refs needed for projects.
func ResolveIngestRoot ¶
ResolveIngestRoot joins workspace with one ingest_roots entry.
func ResolveMiseTOML ¶
ResolveMiseTOML marshals [projects.<slug>.mise] into mise.toml contents.
func RunIngestProject ¶
func RunIngestProject(p Project, workDir string, opts InvariantOptions, report *Report, out *Result) error
RunIngestProject runs ingest checks for every configured root. Failures always stop the project (caller decides multi-project FailFast).
func ScaffoldAttempt ¶
func ScaffoldAttempt(workRoot, destDir string, res MvAttemptResult) error
ScaffoldAttempt writes a fixture scaffold under destDir for a failed attempt. Curate into testdata/mv (or ingest) from these scaffolds — not the reverse.
func ScaffoldMvFixture ¶
ScaffoldMvFixture copies touched files and writes op.json under destDir.
func SetDefaultWorkRoot ¶
func SetDefaultWorkRoot(root string)
SetDefaultWorkRoot overrides the process work-root (tests / explicit reconfig).
func SharedWorkRoot ¶
func SharedWorkRoot() string
SharedWorkRoot is an alias for DefaultWorkRoot (stable path used by Prefetch).
func ValidateOfflineReady ¶
ValidateOfflineReady checks work-root + optional local Docker images for offline use.
func WorkRootPinnedByEnv ¶
func WorkRootPinnedByEnv() bool
WorkRootPinnedByEnv reports whether init took RFT_FUZZY_WORK_ROOT from the environment.
Types ¶
type CatalogCanvas ¶
type CatalogCanvas struct {
Projects []Project
Workspace *Workspace
NoIsolate bool
Offline bool
Strict bool
Log io.Writer
// contains filtered or unexported fields
}
CatalogCanvas runs one-shot mv attempts against warm catalog worktrees. It is safe for sequential use (Go fuzz default). Prefer one canvas per process.
func NewCatalogCanvas ¶
func NewCatalogCanvas(workRoot, catalogPath string, noIsolate bool) (*CatalogCanvas, error)
NewCatalogCanvas builds a canvas over DefaultWorkRoot (or workRoot) and the mv-enabled catalog. Call Ready before Attempt; Ready requires a warm offline work-root (mise run fuzzy:prefetch).
When RFT_FUZZY_PROJECT is set (comma-separated slugs), the canvas is limited to those projects — same filter as Prefetch/Run. That lets campaigns and the seed matrix run against a partially warm work-root (e.g. only workspaced).
func (*CatalogCanvas) Attempt ¶
func (c *CatalogCanvas) Attempt(ctx context.Context, projectIdx int, in PlanInput, scaffoldDir string) (res MvAttemptResult)
Attempt prepares a fresh offline worktree for projectIdx, runs setup, one mv from PlanInput, post-ingest invariants, then the project's catalog check (build/test via mise isolate or host). On bug-class failures, scaffoldDir receives a fixture scaffold for later curation into testdata/mv or ingest.
Serialized: bare git caches are not safe for concurrent worktree add/remove (Go fuzz workers share this canvas).
func (*CatalogCanvas) Project ¶
func (c *CatalogCanvas) Project(i int) Project
Project returns projects[i%len] for fuzz projectIdx.
func (*CatalogCanvas) Ready ¶
func (c *CatalogCanvas) Ready() error
Ready validates the work-root can run offline against the canvas projects.
type Event ¶
type Event struct {
Time string `json:"time"`
Project string `json:"project"`
Iteration int `json:"iteration,omitempty"`
Kind string `json:"kind"`
Placement string `json:"placement,omitempty"`
Source string `json:"source,omitempty"`
Dest string `json:"destination,omitempty"`
Outcome string `json:"outcome"`
Class string `json:"class,omitempty"`
Error string `json:"error,omitempty"`
Log string `json:"log,omitempty"` // report-relative dir with full stdout/stderr
ExitCode int `json:"exit_code,omitempty"`
Failures []InvariantFailure `json:"failures,omitempty"`
DurationMs int64 `json:"duration_ms,omitempty"`
}
Event is one line in events.jsonl.
type GuardError ¶
type GuardError struct {
Reason string
}
GuardError is returned when host-side execution is refused.
func (*GuardError) Error ¶
func (e *GuardError) Error() string
type InvariantFailure ¶
InvariantFailure is one graph consistency problem.
func CheckIdempotentIngest ¶
func CheckIdempotentIngest(dir string, first *ingest.Result) []InvariantFailure
CheckIdempotentIngest re-ingests and compares sorted JSON.
func CheckInvariants ¶
func CheckInvariants(dir string, result *ingest.Result, opts InvariantOptions) []InvariantFailure
CheckInvariants validates an ingest Result against on-disk sources.
func CheckWalkSymbolsSubset ¶
func CheckWalkSymbolsSubset(dir string, result *ingest.Result) []InvariantFailure
CheckWalkSymbolsSubset ensures listed symbols are present as entities.
func RunIngestOnRoot ¶
func RunIngestOnRoot(root string, opts InvariantOptions) (result *ingest.Result, fails []InvariantFailure, err error)
RunIngestOnRoot ingests one directory and checks invariants.
func (InvariantFailure) String ¶
func (f InvariantFailure) String() string
type InvariantOptions ¶
type InvariantOptions struct {
StrictRefs bool
}
InvariantOptions tunes strictness.
type IsolateConfig ¶
type IsolateConfig struct {
Image string `toml:"image"` // default DefaultMiseImage
SetupNetwork *bool `toml:"setup_network"` // default true
CheckNetwork *bool `toml:"check_network"` // default false
Env []string `toml:"env"` // KEY=VAL passed into the container
}
IsolateConfig controls docker/testcontainers execution for setup/check.
func (IsolateConfig) CheckNetworkEnabled ¶
func (c IsolateConfig) CheckNetworkEnabled() bool
CheckNetworkEnabled reports whether checks have network access (default false).
func (IsolateConfig) ImageOrDefault ¶
func (c IsolateConfig) ImageOrDefault() string
ImageOrDefault returns the mise container image.
func (IsolateConfig) SetupNetworkEnabled ¶
func (c IsolateConfig) SetupNetworkEnabled() bool
SetupNetworkEnabled reports whether setup has network access (default true).
type Manifest ¶
type Manifest struct {
Version string `json:"version"`
CreatedAt time.Time `json:"created_at"`
WorkRoot string `json:"work_root"`
Isolation string `json:"isolation"` // "docker" or "host"
Images []string `json:"images,omitempty"`
Projects []ManifestProject `json:"projects"`
}
Manifest records what prefetch populated so offline runs can fail fast.
type ManifestProject ¶
type ManifestProject struct {
ID string `json:"id"`
Ref string `json:"ref"`
Commit string `json:"commit"`
Image string `json:"image"`
ImageKey string `json:"image_key"`
PreserveGlobs []string `json:"preserve_globs,omitempty"`
PreserveOK bool `json:"preserve_ok"`
MiseDataPath string `json:"mise_data_path"`
MiseDataPresent bool `json:"mise_data_present"`
SetupTask string `json:"setup_task,omitempty"`
CheckTask string `json:"check_task,omitempty"`
}
ManifestProject is one catalog entry as prefetched.
type Meta ¶
type Meta struct {
StartedAt string `json:"started_at"`
Seed int64 `json:"seed"`
Iterations int `json:"iterations"`
Mode string `json:"mode"`
Projects []string `json:"projects"`
Commit string `json:"commit,omitempty"`
WorkRoot string `json:"work_root"`
Allow bool `json:"allow"`
NoIsolate bool `json:"no_isolate"`
Offline bool `json:"offline"`
StrictRefs bool `json:"strict_refs"`
}
Meta is written to meta.json.
type MoveNode ¶
type MoveNode struct {
Grain Grain
// Reference is a full path reference (with symbol for atom grain).
Reference string
// Path is the slash path with leading ./ (file or directory).
Path string
// Name is non-empty for atom grain.
Name string
}
MoveNode is an enumerable source at a grain.
type MvAttemptResult ¶
type MvAttemptResult struct {
Plan movePlan
Edits []ingest.Edit
Class string // bug | unsupported | pass | env
Failures []InvariantFailure
Err error
}
MvAttemptResult is the outcome of one open-canvas mv attempt.
func RunMvAttempt ¶
func RunMvAttempt(ctx context.Context, p Project, root string, in PlanInput, strict bool, afterCheck func(context.Context) error, log io.Writer) MvAttemptResult
RunMvAttempt runs on an already-prepared mutable work dir (ingest root). Flow: pre-ingest → pick plan from PlanInput → apply → post invariants → optional afterCheck.
Unsupported picks/applies return Class=unsupported and a nil Err (not a fuzzer crash). Bugs return Class=bug and a non-nil Err suitable for t.Fatal. afterCheck is typically the catalog project's mise test/build (via Session), not fixtures. log receives choose/result lines; nil defaults to os.Stdout.
type MvConfig ¶
type MvConfig struct {
Enabled bool `toml:"enabled"`
Grains []string `toml:"grains"`
Placements []string `toml:"placements,omitempty"`
// Ops is rejected if present (legacy key removed in grain cutover).
Ops []string `toml:"ops,omitempty"`
}
MvConfig controls which move grains (and optional placements) the harness may attempt.
type MvRunOptions ¶
MvRunOptions configures move fuzzing.
type Options ¶
type Options struct {
CatalogPath string
ProjectIDs []string
Mode Mode
Seed int64
Iterations int
WorkRoot string
ReportDir string
Allow bool
NoIsolate bool // opt out of Docker; run setup/check on the host
Offline bool // use work-root caches only; no git fetch; container network=none
// VerifyOffline, when true after prefetch, re-validates offline readiness.
// Prefetch defaults this to true unless NoVerifyOffline is set.
VerifyOffline bool
NoVerifyOffline bool // skip post-prefetch offline verification
StrictRefs bool
FailFast bool
Verbose bool
Grains []string // optional override of project mv grains
Stdout io.Writer
Stderr io.Writer
}
Options configures a harness run.
type PlanInput ¶
type PlanInput struct {
GrainIndex uint8
SourceIndex uint32
PlacementIndex uint8
PeerIndex uint32
Entropy uint32
}
PlanInput is the minimizable decision surface shared by catalog RNG iterations and Go native fuzz (testing.F). Indices are taken mod available options.
func PlanInputFromRand ¶
PlanInputFromRand draws a PlanInput from a seeded RNG (catalog ModeMv/ModeRun).
type PrefetchOptions ¶
type PrefetchOptions struct {
WorkRoot string
CatalogPath string
ProjectIDs []string
NoIsolate bool
Stdout io.Writer
Stderr io.Writer
}
PrefetchOptions configures Prefetch / PrefetchOnce.
type PrepareOptions ¶
type PrepareOptions struct {
Offline bool
// Reuse keeps an existing worktree at the pinned ref (reset in place) instead
// of deleting it. Prefetch sets this so repeated runs are idempotent.
Reuse bool
}
PrepareOptions controls clone, snapshot restore, and reuse behavior.
type Project ¶
type Project struct {
ID string `toml:"-"` // map key under [projects.<slug>]
URL string `toml:"url"`
Ref string `toml:"ref"`
Family string `toml:"family"` // ingest family id (ecma, jvm, go, …)
Language string `toml:"language,omitempty"` // rejected if set (use family)
Root string `toml:"root"`
Mise map[string]any `toml:"mise"` // embedded mise.toml root ([projects.<slug>.mise]…)
SetupTask string `toml:"setup_task"` // default "setup" when mise embedded; "-" skips
CheckTask string `toml:"check_task"` // default "test" when mise embedded
Setup []string `toml:"setup"` // legacy argv fallback without embedded mise
Check []string `toml:"check"` // legacy argv fallback without embedded mise
IngestRoots []string `toml:"ingest_roots"`
Mv MvConfig `toml:"mv"`
Isolate IsolateConfig `toml:"isolate"`
PreserveGlobs []string `toml:"preserve_globs"`
SkipIf string `toml:"skip_if,omitempty"`
LocalPath string `toml:"local_path,omitempty"` // test-only: skip clone, use path
}
Project is one real-world target from the fuzzy catalog.
func FilterProjects ¶
FilterProjects returns projects matching ids (empty ids = all).
func LoadCatalog ¶
LoadCatalog reads and validates projects.toml. Projects are keyed by slug: [projects.<slug>].
func LoadCatalogCanvas ¶
LoadCatalogCanvas returns catalog projects with mv enabled — the open canvas for Go native fuzz and for catalog ModeMv/ModeRun. Fixtures under testdata/ are not canvas inputs; they are curated later from bug scaffolds.
type Report ¶
Report is the on-disk run report.
func NewReport ¶
NewReport creates base/<timestamp>-<seed>/. When base is empty, reports live under work-root/reports (meta.WorkRoot, or DefaultWorkRoot() from package init / SetDefaultWorkRoot).
func (*Report) LogPath ¶
LogPath returns the absolute path for a report-relative log dir from WriteRunResult.
func (*Report) ScaffoldDir ¶
type RunResult ¶
type RunResult struct {
Args []string
Dir string
ExitCode int
Stdout string
Stderr string
Err error
Isolated bool
}
RunResult captures command output and status.
type Runner ¶
type Runner struct {
NoIsolate bool
// Offline disables package-manager network and requires local docker images.
Offline bool
// DataRoot holds persistent caches across projects (work-root/mise-data).
DataRoot string
// Verbose is reserved for extra harness noise; command stdout/stderr always
// stream live when Stdout/Stderr/Log is set, and are still captured for reports.
Verbose bool
// Log receives progress lines always (session start/stop, exec labels).
Log io.Writer
// Stdout/Stderr receive live command output (also used as fallback for Log).
Stdout io.Writer
Stderr io.Writer
}
Runner creates isolation sessions backed by testcontainers.
func (Runner) Run ¶
func (r Runner) Run(ctx context.Context, cfg IsolateConfig, dir, imageKey string, argv []string, network bool) (res RunResult)
Run is a one-shot helper that starts a session, runs argv, and closes it. Prefer StartSession when setup and check must share state.
func (Runner) StartSession ¶
func (r Runner) StartSession(ctx context.Context, cfg IsolateConfig, dir, imageKey string, network bool) (*Session, error)
StartSession starts a reusable container with the worktree and tool caches mounted. network follows setup_network (check reuses the same networked session).
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is one long-lived mise container reused for setup and checks.
type Workspace ¶
type Workspace struct {
Root string
}
Workspace manages cached bare clones and mutable worktrees.
func NewWorkspace ¶
func (*Workspace) BuildManifest ¶
func (w *Workspace) BuildManifest(projects []Project, noIsolate bool, commits map[string]string) Manifest
BuildManifest constructs a manifest from the current work-root state for projects.
func (*Workspace) HasPreserveSnapshot ¶
HasPreserveSnapshot reports whether a usable durable snapshot exists.
func (*Workspace) LoadManifest ¶
LoadManifest reads work-root/manifest.json.
func (*Workspace) MiseDataRoot ¶
MiseDataRoot is work-root/mise-data (tool and package-manager caches).
func (*Workspace) Prepare ¶
func (w *Workspace) Prepare(p Project, runID string, opts PrepareOptions) (workDir string, commit string, err error)
Prepare returns a work directory at the project pin. When offline, uses the bare cache only (no git fetch/clone from URL) and requires preserve snapshots written by prefetch.
func (*Workspace) ReportsDir ¶
ReportsDir is work-root/reports (event logs and scaffolds for harness runs).
func (*Workspace) Reset ¶
Reset restores the workdir to the pinned ref, preserving configured globs.
func (*Workspace) RestorePreserveSnapshot ¶
RestorePreserveSnapshot overlays durable preserve snapshots onto workDir.
func (*Workspace) SaveManifest ¶
SaveManifest writes manifest.json under work-root.
func (*Workspace) SavePreserveSnapshot ¶
SavePreserveSnapshot copies configured preserve_globs from workDir into the durable work-root snapshot used by later Prepare calls (especially --offline). The swap is atomic so a failed save leaves the previous snapshot intact.