facts

package
v0.34.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package facts interprets the declared project.md layers, merges them with the detection probes and the contract's defaults, and attributes every effective value to its origin. It is the one component of f10 allowed to interpret instruction prose - bin/f10-load-project.sh stays a concatenator.

Interpretation stays shallow: only the sub-facts with a fixed vocabulary (Layering, Visibility, Storage, the tracker kind and its id prefix, the remote review's four facts) become structure; everything else is shown as the declared prose, attributed but unparsed. The binary may be incomplete, never wrong - what it cannot place it shows as-is instead of guessing.

It writes that prose too, in scaffold.go: `f10 init` renders detection as a project.md. Reader and writer share a package so the vocabulary one keys on and the words the other emits cannot drift apart.

Index

Constants

View Source 
const (
	OriginDetected = "detected"
	OriginDefault  = "default"
	OriginAbsent   = "absent"
)

Origins an effective value can have. Declared origins are qualified by the layer label at build time: "declared (main)", "declared (worktree)".

View Source 
const (
	ReviewerBot   = "bot"
	ReviewerHuman = "human"
	ReviewerCheck = "check"

	ArrivesComment = "issue comment"
	ArrivesInline  = "inline review"
	ArrivesCheck   = "check run"

	TriggerAutomatic = "automatic"
	TriggerManual    = "manual"

	DonePosted    = "posted"
	DoneMarker    = "marker"
	DoneSubmitted = "submitted"
	DoneConcluded = "concluded"

	HandledReaction = "reaction"
	HandledMarker   = "marker"
	HandledCheckbox = "checkbox"
	HandledThread   = "thread resolved"
)

The vocabularies, as the words the parser looks for.

View Source 
const DefaultDriveChain = "plan → judge → ship → review → resolve → finish"

DefaultDriveChain is the chain `f10 drive` runs each task through when project.md declares none: review after ship reviews the shipment, and resolve settles it before finish merges.

Variables

View Source 
var ErrHasFrontmatter = errors.New("already has a frontmatter block")

ErrHasFrontmatter refuses a second migration.

Functions

This section is empty.

Types

type Declared added in v0.29.0 

type Declared struct {
	Visibility  string           `yaml:"visibility,omitempty"`
	Storage     string           `yaml:"storage,omitempty"`
	Layering    string           `yaml:"layering,omitempty"`
	Tracker     TrackerDecl      `yaml:"tracker,omitempty"`
	MergeMethod string           `yaml:"merge_method,omitempty"`
	Catchup     string           `yaml:"catchup,omitempty"`
	Pipelines   map[string]Steps `yaml:"pipelines,omitempty"`
	Planless    []string         `yaml:"planless,omitempty"`
	DriveChain  Steps            `yaml:"drive_chain,omitempty"`
	Review      ReviewDecl       `yaml:"review,omitempty"`
	Standup     StandupDecl      `yaml:"standup,omitempty"`
}

Declared is one layer's frontmatter.

type Draft 

type Draft struct {
	Markdown string
	Keys     []string
	Sections []string
	Omitted  []string
}

A Draft is one rendered project.md: the markdown, the frontmatter keys and prose sections it carries, and the sections left out because nothing detected them.

func Scaffold 

func Scaffold(lay *layout.Layout, pb *probe.Probes, eff *Effective) (*Draft, error)

Scaffold renders a project.md for a checkout that declares none. Pure: the caller owns the filesystem, this owns the contract.

type Effective 

type Effective struct {
	Fields       []Field `json:"fields"`
	Unrecognized []Field `json:"unrecognized,omitempty"`

	// The fixed-vocabulary sub-facts.
	Layering        string `json:"layering"`
	Visibility      string `json:"visibility"`
	Storage         string `json:"storage"`
	TrackerKind     string `json:"trackerKind,omitempty"`
	IDPrefix        string `json:"idPrefix,omitempty"`        // "ABC", "F10" - the task id format's letters
	IDPrefixOrigin  string `json:"idPrefixOrigin,omitempty"`  // "declared (<layer>)" or "derived from project name <name>"
	IDPrefixDerived bool   `json:"idPrefixDerived,omitempty"` // the prefix came from the project's name, not a declaration

	// The remote review's four facts (review.go); zero when Review declares
	// no remote reviewer.
	Review Review `json:"review"`

	// The rest of the typed facts (resolve.go). MergeMethod "" means none
	// declared: finish asks the repo.
	MergeMethod string              `json:"mergeMethod,omitempty"`
	Catchup     string              `json:"catchup"`
	Pipelines   map[string][]string `json:"pipelines"`
	Planless    []string            `json:"planless,omitempty"`
	DriveChain  []string            `json:"driveChain"`
	UpkeepPaths []string            `json:"upkeepPaths,omitempty"` // standup.upkeep: globs on top of the defaults

	// Facts is every typed value with its origin; Problems what is wrong
	// with how they were declared.
	Facts    []Fact    `json:"facts"`
	Problems []Problem `json:"problems,omitempty"`
	// contains filtered or unexported fields
}

Effective is the merged, attributed view of a project's configuration.

func Build 

func Build(lay *layout.Layout, pb *probe.Probes) *Effective

Build merges the declared layers with detection and the contract's defaults into one attributed view.

func (*Effective) Errors added in v0.29.0 

func (e *Effective) Errors() string

Errors are the problems that stop a command, joined for its message.

type Fact added in v0.29.0 

type Fact struct {
	Key    string `json:"key"`
	Value  string `json:"value"`
	Origin string `json:"origin"`
}

A Fact is one typed value and where it came from.

type Field 

type Field struct {
	Name   string `json:"name"`
	Value  string `json:"value"`
	Prose  bool   `json:"prose,omitempty"`  // multi-line prose, not a scalar
	Origin string `json:"origin"`           // "detected", "declared (<layer>)", "default", "absent"
	Source string `json:"source,omitempty"` // file for declared, evidence for detected
}

A Field is one effective configuration value with its provenance.

type Migration added in v0.29.0 

type Migration struct {
	Content    string
	Moved      []string // the frontmatter keys written
	Superseded []string // "<key>: <where in the prose>"
}

A Migration is what `f10 init --migrate` makes of one prose-only project.md: the file with a frontmatter block on top, and the prose each moved fact came from, for the user to delete.

func Migrate added in v0.29.0 

func Migrate(data []byte, path string) (*Migration, error)

Migrate reads the facts one project.md declares in prose, with the same readers the fallback uses, and puts them in a frontmatter block above the untouched file. Only what the file declares moves: defaults and detection stay out, so the block says no more than the prose did.

type Problem added in v0.29.0 

type Problem struct {
	Error   bool   `json:"error,omitempty"`
	Message string `json:"message"`
}

A Problem is something wrong with the declaration. An error stops the commands that act on facts; a warning is shown and nothing else.

type Review added in v0.26.0 

type Review struct {
	Reviewer     string `json:"reviewer,omitempty"`     // the identity: a login, or a check's name
	ReviewerKind string `json:"reviewerKind,omitempty"` // bot | human | check
	Arrives      string `json:"arrives,omitempty"`      // issue comment | inline review | check run
	Trigger      string `json:"trigger,omitempty"`      // automatic | manual | automatic, manual
	TriggerHow   string `json:"triggerHow,omitempty"`   // the rest of the line: how a human fires it
	Done         string `json:"done,omitempty"`         // posted | marker | submitted | concluded
	DoneText     string `json:"doneText,omitempty"`     // the marker's text
	Handled      string `json:"handled,omitempty"`      // reaction | marker | checkbox | thread resolved
	HandledText  string `json:"handledText,omitempty"`  // the reaction's emoji, or the marker's text
}

A Review is the parsed remote-review contract. The zero value means the section declares no remote reviewer, which is the common case.

func (Review) Missing added in v0.26.0 

func (r Review) Missing() []string

Missing names the facts a remote review still lacks, in contract order, so a refusal can say which line to fix.

func (Review) Remote added in v0.26.0 

func (r Review) Remote() bool

Remote reports whether the section names a remote reviewer at all.

type ReviewDecl added in v0.29.0 

type ReviewDecl struct {
	Reviewer string `yaml:"reviewer,omitempty"`
	Arrives  string `yaml:"arrives,omitempty"`
	Trigger  string `yaml:"trigger,omitempty"`
	Done     string `yaml:"done,omitempty"`
}

ReviewDecl is the remote review's four facts, in the vocabulary the prose items use, so the same sub-parsers read both.

type StandupDecl added in v0.33.0 

type StandupDecl struct {
	Upkeep []string `yaml:"upkeep,omitempty"`
}

StandupDecl is what `f10 standup` reads: the paths that, alone in a commit, make it upkeep, on top of the lockfiles, generated files and snapshots it knows (schema dumps, a project's own codegen output).

type Steps added in v0.29.0 

type Steps []string

Steps is an ordered list of names, written as a YAML list or as one `a → b → c` string.

func (*Steps) UnmarshalYAML added in v0.29.0 

func (s *Steps) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML accepts a sequence of strings or one arrow-separated string.

type TrackerDecl added in v0.29.0 

type TrackerDecl struct {
	Kind string `yaml:"kind,omitempty"`
	ID   string `yaml:"id,omitempty"`
}

TrackerDecl is the tracker's kind and its task id format (`FT-###`).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.