docfidelity

Documentation

Overview

Package docfidelity is the doc-fidelity gate over the brief (itd-60, spc-2609020903498198): the brief describes every surface that ships, or the intent does not reach shipped.

Index

• Constants
• func Armed(root string) bool
• func UnlandedFlags(root string) ([]lint.BriefFlagMiss, error)
• type Edit
• type Flag
  • func Apply(root string, edits []Edit, commit string, at time.Time) ([]Flag, error)
• type Inputs
  • func ReadInputs(root string, commands []surface.Command, population []string) (Inputs, error)
• type Kind
• type Request
  • func NewRequest(commit string, in Inputs) Request
• type Review
  • func Record(root string, raw []byte, at time.Time) (string, Review, error)
• type ReviewStatus
• type Reviewer
• type Row
• type SavedReview
  • func (s SavedReview) Review() Review
• type Sentence
• type Surface
  • func ShippedForTest(commands []surface.Command, agents []string) []Surface
  • func (s Surface) Key() string
• type Verdict
  • func Enforce(root string, commands []surface.Command, population []string) (v Verdict, armed bool, err error)
  • func Gate(root string, commands []surface.Command, population []string, report bool) (v Verdict, armed bool, err error)

Constants

const (
	DocBrief  = "brief"
	DocPublic = "public"
)

Doc kinds a reviewed sentence stands in.

const (
	// GateName is the receipt's detector and its file name.
	GateName = "doc-fidelity"
	// ReceiptsDir holds the saved reviews, <dir>/<commit>/doc-fidelity.json.
	// It is the local tier, as the preflight receipts are: a review is a fact
	// about one commit on one machine, found by the verbs that close and cut.
	ReceiptsDir = ".abcd/.work.local/doc-fidelity"
	// ChaptersDir is the brief's surface chapters.
	ChaptersDir = ".abcd/development/brief/04-surfaces"
	// SnapshotPath is the committed command-tree snapshot. Its presence arms
	// the gate: it marks the repository whose binary the brief describes.
	SnapshotPath = ".abcd/development/release/surface.json"
	// AgentsDir is the plugin's agent prompts, one <name>.md per agent.
	AgentsDir = "agents"
)

const FlagsPath = ".abcd/work/brief-review-flags.json"

FlagsPath is the review-flag ledger: every drafted edit the gate applied, kept until the product thinker has read it and removes its entry. It is in the shared working tier, so the flag travels in the change's own diff.

const RunReviewFirst = "run the docs review first"

RunReviewFirst is the words every missing, stale or unusable review refusal carries (ruling DR3).

const VerdictShape = `{"verificationResult": "PROMOTE|HOLD|INCONCLUSIVE", "judgeModel": "<pinned model id>", ` +
	`"tier": "full|shallow", "failing": [{"doc": "brief|public", "chapter": "<04-surfaces file or public doc>", ` +
	`"sentence": "<the false sentence, verbatim, from one line>", "replacement": "<drafted correction, optional>", ` +
	`"evidence": "<file:line showing the divergence>", "disposition": "confirmed"}]}`

VerdictShape is the payload `abcd docs fidelity record` accepts.

Functions

func Armed

func Armed(root string) bool

Armed reports whether the repository ships the binary the gate judges: it carries the command-tree snapshot and the brief's surface chapters. Another repository's brief does not describe abcd's verbs, so it is not judged.

func UnlandedFlags

func UnlandedFlags(root string) ([]lint.BriefFlagMiss, error)

UnlandedFlags reports each review flag whose replacement no line of its chapter contains (iss-2610050259233425): Apply flags the drafted replacement, and a sentence tidied by hand before the commit leaves the flag naming text the brief does not carry, so the record of what the product thinker must read is wrong. A flag records the sentence as committed; one that does not is returned, on its replacement's line in the flags file, for record-lint's brief_flag_landed rule (registered through lint.SetBriefFlagCheck). No flags file is no flag; a flags file that cannot be read is an error, never an empty report.

Types

type Edit

type Edit struct {
	Chapter     string `json:"chapter"`
	Sentence    string `json:"sentence"`
	Replacement string `json:"replacement"`
	Evidence    string `json:"evidence"`
}

Edit is a proposed brief edit: replace Sentence in Chapter by Replacement.

type Flag

type Flag struct {
	Chapter     string `json:"chapter"`
	Sentence    string `json:"sentence"`
	Replacement string `json:"replacement"`
	Evidence    string `json:"evidence,omitempty"`
	Commit      string `json:"commit"`
	Applied     string `json:"applied"`
}

Flag is the review flag an applied edit records: the brief carries a sentence nobody but the reviewer wrote until the product thinker reads it.

func Apply

func Apply(root string, edits []Edit, commit string, at time.Time) ([]Flag, error)

Apply writes each edit into its chapter and records one flag per edit, naming the reviewed commit. Every edit is checked before anything is written: a chapter outside the surfaces directory, a sentence or replacement that is not one bounded line, or a sentence the chapter does not carry exactly once, refuses the whole apply and writes nothing.

type Inputs

type Inputs struct {
	Commands   []surface.Command
	Agents     []string
	Chapters   map[string]string
	Population []string
	Flags      []Flag
}

Inputs is everything the judgement reads.

func ReadInputs

func ReadInputs(root string, commands []surface.Command, population []string) (Inputs, error)

ReadInputs reads the chapters, the agent set and the review flags beside the command tree the caller derived from the binary. No file exempts a surface from layer 1: every surface the binary ships is named by a chapter or refuses.

type Kind

type Kind string

Kind is the kind of shipped surface.

const (
	KindVerb    Kind = "verb"
	KindSubVerb Kind = "sub-verb"
	KindAgent   Kind = "agent"
)

type Request

type Request struct {
	Commit     string   `json:"commit"`
	Population []string `json:"population"`
	Chapters   []string `json:"chapters"`
	RecordWith string   `json:"record_with"`
	Shape      string   `json:"verdict_shape"`
}

Request is what an unattended routine hands the delegated reviewer, the way `launch ship` hands the changelog composer its request block: the commit to review, the population whose delivery is judged, the chapters to read, and the verb that saves the verdict.

func NewRequest

func NewRequest(commit string, in Inputs) Request

NewRequest composes the reviewer's request for commit.

type Review

type Review struct {
	Status   ReviewStatus `json:"status"`
	Commit   string       `json:"commit"`
	Named    string       `json:"named,omitempty"`
	Verdict  string       `json:"verdict,omitempty"`
	Problems []string     `json:"problems,omitempty"`
	Findings []Sentence   `json:"findings,omitempty"`
}

Review is layer 2's answer.

func Record

func Record(root string, raw []byte, at time.Time) (string, Review, error)

Record validates the reviewer's verdict and saves it as the receipt for the commit the checkout stands at, returning the receipt's repo-relative path and the review as the gate now reads it. A refused payload writes nothing.

type ReviewStatus

type ReviewStatus string

ReviewStatus is what the saved review says about the code under judgement.

const (
	ReviewMatch        ReviewStatus = "match"
	ReviewNone         ReviewStatus = "none"
	ReviewStale        ReviewStatus = "stale"
	ReviewInvalid      ReviewStatus = "invalid"
	ReviewHold         ReviewStatus = "hold"
	ReviewInconclusive ReviewStatus = "inconclusive"
)

type Reviewer

type Reviewer interface{ Review() Review }

Reviewer is the delegated layer.

type Row

type Row struct {
	Surface
	Chapter string `json:"chapter,omitempty"`
}

Row is one coverage row.

type SavedReview

type SavedReview struct{ Root, Commit string }

SavedReview is layer 2 as ruled: the review the delegated reviewer saved for Commit, found in Root.

func (SavedReview) Review

func (s SavedReview) Review() Review

Review reads the saved review. Every way of not having a usable verdict is a status that refuses; none is a pass.

type Sentence

type Sentence struct {
	Doc      string `json:"doc"`
	Chapter  string `json:"chapter"`
	Sentence string `json:"sentence"`
	Evidence string `json:"evidence"`
	// Replacement is the reviewer's drafted sentence, "" when none was drafted.
	Replacement string `json:"replacement,omitempty"`
}

Sentence is one sentence a reviewer judged false.

type Surface

type Surface struct {
	Kind Kind   `json:"kind"`
	Name string `json:"name"`
}

Surface is one shipped surface.

func ShippedForTest

func ShippedForTest(commands []surface.Command, agents []string) []Surface

ShippedForTest is shipped, for a test outside this package that builds a repository whose brief names every shipped surface: a declared cross-package test seam, which the core reach audit leaves out.

func (Surface) Key

func (s Surface) Key() string

Key is the surface's sort key: the command path for a verb or sub-verb, "agent:<name>" for an agent.

type Verdict

type Verdict struct {
	Report     bool       `json:"report"`
	Population []string   `json:"population"`
	Coverage   []Row      `json:"coverage"`
	Uncovered  []Surface  `json:"uncovered"`
	Review     *Review    `json:"review,omitempty"`
	False      []Sentence `json:"false_sentences"`
	Public     []Sentence `json:"public_findings"`
	Proposed   []Edit     `json:"proposed_edits"`
	Applied    []Sentence `json:"applied_edits"`
	Refuse     bool       `json:"refuse"`
	Reasons    []string   `json:"reasons"`
}

Verdict is the judgement.

func Enforce

func Enforce(root string, commands []surface.Command, population []string) (v Verdict, armed bool, err error)

Enforce is what both enforcement points run, `spec close` and `launch ship`, with their population. Layer 1 runs whatever the population: a close or a cut that ships no intent can still carry a surface an issue fix added, and the coverage floor is cheap enough to run at every enforcement point (spc-2609020903498198). Layer 2's saved review is required only where an intent ships (iss-2610020728118137), so with no population this is layer 1 alone and no review is read.

func Gate

func Gate(root string, commands []surface.Command, population []string, report bool) (v Verdict, armed bool, err error)

Gate is both layers: what the per-task report calls, and what Enforce runs for a population of one intent at `spec close` or every intent shipped since the last tag at `launch ship`. armed is false, with a zero verdict, where the repository does not ship the binary the gate judges.