cellcoverage

Documentation

Overview

Package cellcoverage provides per-cell test fixtures for the M-0124 + M-0125 positive/negative coverage milestones. A CellFixture is an isolated tmp git repo with `aiwf init` already run; its methods walk the kernel's verb surface in-process (no subprocess fork) to bring an entity to a (Kind, FromState) point or to mutate the fixture so it satisfies a spec.Predicate.

Why in-process for fixture setup: M-0137 retrofit's insight is "don't fork when you don't have to." The cell-under-test still runs via subprocess (testutil.RunBin) — the integration seam matters there. Fixture preparation doesn't test flag parsing or exit codes; calling verb.Add / verb.Promote / verb.Apply directly produces the same on-disk + frontmatter state in ~10ms instead of ~80ms per fork.

Index

• func LookupComposite(tr *tree.Tree, compositeID string) (*entity.Entity, *entity.AcceptanceCriterion, error)
• type BringOpts
• type CellFixture
  • func NewCellFixture(t *testing.T) *CellFixture
  • func (f *CellFixture) AuthorizeScope(t *testing.T, entityID, agent string) *scope.Scope
  • func (f *CellFixture) BringEntityToState(t *testing.T, k entity.Kind, fromState string, opts BringOpts) string
  • func (f *CellFixture) Must(res *verb.Result, err error) *verb.Result
  • func (f *CellFixture) SatisfyPredicate(t *testing.T, p spec.Predicate, entityID string, evalCtx *spec.EvalContext)
  • func (f *CellFixture) Tree() *tree.Tree

Functions

func LookupComposite

func LookupComposite(tr *tree.Tree, compositeID string) (*entity.Entity, *entity.AcceptanceCriterion, error)

LookupComposite resolves a composite id (M-NNNN/AC-N) to its parent milestone + the specific AC slot. Returns an error when the id shape is malformed, the milestone is missing, or the AC slot doesn't exist. Exported so per-cell drivers (M-0124's positive driver, M-0125's negative driver) reuse the same logic rather than carrying their own copies — closes G-0159.

Types

type BringOpts

type BringOpts struct {
	ParentTDD string // override default "required" for milestone parents
	ACs       int    // populated-fixture knob: seed N met ACs
}

BringOpts controls knobs of BringEntityToState that some cells need (e.g., a non-default parent.tdd policy, an AC count to seed for the populated-fixture variant of Milestone.done).

Zero-value fields mean "use the conventional default":

• ParentTDD: "required" for milestones (matches the parent.tdd == "required" predicate used in AC sub-cells)
• ACs: 0 for milestone targets (the vacuous-satisfaction path for Milestone.done; the spec's AntiRule says a milestone is not required to have >=1 AC)

type CellFixture

type CellFixture struct {
	Root string
	// contains filtered or unexported fields
}

CellFixture is a fresh isolated repo with aiwf init applied. Methods walk the kernel's verb surface in-process to drive the fixture to the required state. The cell-under-test in the per-cell driver runs against this same Root via subprocess.

Carries the *testing.T it was constructed with so method calls can fail-fast via t.Fatalf without each call site marshaling the t parameter through. Pattern matches internal/verb/verb_test.go's runner.

func NewCellFixture

func NewCellFixture(t *testing.T) *CellFixture

NewCellFixture sets up an isolated repo:

1. t.TempDir for the root
2. git init + identity config
3. initrepo.Init to lay down aiwf.yaml + framework artifacts

Returns a *CellFixture whose methods drive subsequent state. Bootstrap cost is dominated by initrepo.Init (~30-60ms; one-time per test). Compared to a subprocess `aiwf init`, the saving is the fork itself (~20-40ms).

func (*CellFixture) AuthorizeScope

func (f *CellFixture) AuthorizeScope(t *testing.T, entityID, agent string) *scope.Scope

AuthorizeScope opens an `aiwf authorize` scope on entityID for the named agent (e.g. "ai/claude"), commits it in-process, and returns the resulting active scope — loaded back through the same git-log reader (cliutil.LoadEntityScopes) the cmd layer uses, so a driver consuming the scope sees exactly what a production verb invocation would.

The scope-entity must already be non-terminal (the authorize verb refuses otherwise); the caller brings it up first. Fails the test if the authorize commit or the round-trip load does not yield an active scope.

func (*CellFixture) BringEntityToState

func (f *CellFixture) BringEntityToState(t *testing.T, k entity.Kind, fromState string, opts BringOpts) string

BringEntityToState walks the verb sequence required to produce an entity of kind k at fromState, returning its id. The dispatch table is the per-kind FSM walk; the chosen path is the shortest legal sequence from a fresh repo.

For sub-kinds (spec.KindAC, spec.KindTDDPhase) the helper first constructs the parent milestone (in_progress) then adds the AC and walks its sub-FSM.

The Milestone.done path takes the zero-AC vacuous-satisfaction route by default (spec AntiRule: a milestone is not required to have >= 1 AC). BringOpts.ACs > 0 selects the populated path.

func (*CellFixture) Must

func (f *CellFixture) Must(res *verb.Result, err error) *verb.Result

Must commits a verb.Result's plan. Mirrors the runner.must pattern from internal/verb/verb_test.go: asserts no Go error, no error-severity findings, plan present, then verb.Apply. Call sites pass the verb's (res, err) tuple directly:

f.Must(verb.Add(f.ctx, f.Tree(), ...))

func (*CellFixture) SatisfyPredicate

func (f *CellFixture) SatisfyPredicate(t *testing.T, p spec.Predicate, entityID string, evalCtx *spec.EvalContext)

SatisfyPredicate mutates the fixture so that p holds against the entity identified by entityID. Each supported (Subject, Op) atom has a hand-rolled mutation; after applying, the helper re-loads the tree and calls spec.EvaluatePredicate to self-verify — the silent-drift guard. evalCtx is updated in place when the predicate is verb-arg-shaped (self.target-state, self.evidence).

func (*CellFixture) Tree

func (f *CellFixture) Tree() *tree.Tree

Tree re-loads the on-disk tree. Each call walks the filesystem; callers re-load after any state mutation so they see the post- mutation shape.