trunk

Documentation

Overview

Package trunk reads entity ids from the configured trunk ref's tree, applying the policy from id-allocation.md:

• Not a git repository at all → skip. Tooling that legitimately runs outside a repo (test fixtures, exploratory invocations on plain directories) has no cross-branch surface to police.

• Configured trunk ref resolves → return the (kind, id, path) triples found under work/ and docs/adr/ in that ref's tree.

• Trunk ref missing AND was explicitly set in aiwf.yaml → hard error. The user named a specific ref; if it doesn't exist they should fix the typo or fetch it. Silent degradation would defeat their explicit intent.

• Trunk ref missing AND was the default (no allocate.trunk in aiwf.yaml) AND no refs/remotes/* tracking refs exist → skip. Covers "no remote configured" (sandbox repos), "remote configured but never fetched" (transient setup), and "freshly cloned an empty bare" (canonical first-push setup, where the bare has no branches so the clone has none either). None has anything to collide with.

• Trunk ref missing AND was the default AND tracking refs DO exist → hard error. The remote has been populated; an unresolvable default trunk is a real misconfiguration (the team's trunk is named something other than main, or the consumer hasn't fetched it). Setting allocate.trunk in aiwf.yaml fixes it.

The package is read-only and has no per-process cache; callers invoke once per verb run.

Index

• type ID
• type Result
  • func Read(ctx context.Context, workdir string, cfg *config.Config) (Result, error)
  • func (r Result) IDStrings() []string

Types

type ID

type ID struct {
	Kind entity.Kind
	ID   string
	Path string
}

ID names one entity that exists in the trunk ref's tree, by kind, id string, and the repo-relative path the trunk has it at.

type Result

type Result struct {
	IDs     []ID
	Skipped bool
}

Result carries the trunk ids visible to the allocator and the cross-tree check. Skipped is true when the repo has no remotes and the trunk read was deliberately bypassed.

func Read

func Read(ctx context.Context, workdir string, cfg *config.Config) (Result, error)

Read returns the entity ids in cfg's configured trunk ref, following the policy in this package's doc comment.

cfg may be nil — in which case the default trunk ref is used. Callers pass workdir as the consumer repo root.

func (Result) IDStrings

func (r Result) IDStrings() []string

IDStrings returns just the id strings from r, in the order they appear in r.IDs. Convenience for AllocateID, which only needs the id values.