commentpass

Documentation

Overview

Package commentpass strips every comment a plan branch added to production code, hands them to a judge as text, and reconstructs each file from its snapshot minus the drops. Nothing here holds a model; the judge reads one file and writes one JSON.

Index

• Variables
• func DropInScope(rel string) bool
• func InScope(rel string) bool
• func KeyOf(path string, lines []string) string
• func Normalise(lines []string) string
• type Anchor
• type Block
• type Candidate
• type Counts
• type Cycle
• type Drop
• type FileEntry
• type FormatTSFunc
• type Keep
• type KeepVerdict
• type Kind
• type Ledger
• type Manifest
• type Pass
  • func New(root, plan string, stdout io.Writer) *Pass
  • func (p *Pass) Apply(ctx context.Context, verdictsPath, candidatesPath string, cycle int, ...) error
  • func (p *Pass) Drop(ctx context.Context, refs []string, cycle int, message string) error
  • func (p *Pass) Strip(ctx context.Context, outDir string, all bool) error
  • func (p *Pass) Verify(ctx context.Context) error
• type RunFunc
• type Span
• type Verdicts

Variables

var ErrRefused = errors.New("refused")

ErrRefused marks a refusal that wrote nothing.

var ScopePrefixes = []string{"cmd/", "internal/", "web/src/"}

ScopePrefixes are the directories the pass reads; test files inside them are excluded.

Functions

func DropInScope

func DropInScope(rel string) bool

func InScope

func InScope(rel string) bool

InScope reports whether a repo-relative path is production code the pass may touch.

func KeyOf

func KeyOf(path string, lines []string) string

KeyOf identifies a comment by path and normalised text across cycles.

func Normalise

func Normalise(lines []string) string

Normalise reduces comment lines to their words, so a formatter rewrap never changes a key.

Types

type Anchor

type Anchor struct {
	Kind string `json:"kind"`
	Text string `json:"text"`
	Line int    `json:"line"`
}

Anchor says where a comment sat, for a reader; correctness never relocates by it.

type Block

type Block struct {
	Kind      Kind     `json:"kind"`
	Span      Span     `json:"span"`
	StartLine int      `json:"start_line"`
	EndLine   int      `json:"end_line"`
	Lines     []string `json:"lines"`
}

Block is one judgeable comment: consecutive own-line comment lines, or one segment.

type Candidate

type Candidate struct {
	ID       string   `json:"id"`
	Path     string   `json:"path"`
	Key      string   `json:"key"`
	Kind     Kind     `json:"kind"`
	Span     Span     `json:"span"`
	Lines    []string `json:"lines"`
	Anchor   Anchor   `json:"anchor"`
	Origin   string   `json:"origin"`
	Added    int      `json:"added_lines"`
	Total    int      `json:"total_lines"`
	Previous []string `json:"previous,omitempty"`
	Names    []string `json:"names,omitempty"`
	Doc      string   `json:"doc,omitempty"`
	Note     string   `json:"note,omitempty"`
}

Candidate is one block the judge rules on.

type Counts

type Counts struct {
	Candidates int `json:"candidates"`
	Keep       int `json:"keep"`
	Drop       int `json:"drop"`
}

type Cycle

type Cycle struct {
	Cycle  int    `json:"cycle"`
	At     string `json:"at"`
	By     string `json:"by"`
	Counts Counts `json:"counts"`
	Keeps  []Keep `json:"keeps"`
	Drops  []Drop `json:"drops"`
}

Cycle is one apply or drop run.

type Drop

type Drop struct {
	Key    string   `json:"key"`
	Path   string   `json:"path"`
	Anchor Anchor   `json:"anchor"`
	Lines  []string `json:"lines"`
}

type FileEntry

type FileEntry struct {
	Path        string      `json:"path"`
	Original    string      `json:"original"`
	StrippedSHA string      `json:"stripped_sha256"`
	Dirty       bool        `json:"dirty"`
	Candidates  []Candidate `json:"candidates"`
}

FileEntry snapshots one file: its exact bytes before strip, what strip wrote, and its candidates in file order.

type FormatTSFunc

type FormatTSFunc func(ctx context.Context, root string, rels []string) error

FormatTSFunc formats the given repo-relative TypeScript files in place.

type Keep

type Keep struct {
	Key    string   `json:"key"`
	Path   string   `json:"path"`
	Anchor Anchor   `json:"anchor"`
	Lines  []string `json:"lines"`
	Reason string   `json:"reason"`
}

type KeepVerdict

type KeepVerdict struct {
	ID     string `json:"id"`
	Reason string `json:"reason"`
}

type Kind

type Kind string

Kind says how a block sits in the file: own-line lines removed whole, or a segment sharing a line with code.

const (
	KindBlock   Kind = "block"
	KindSegment Kind = "segment"
)

type Ledger

type Ledger struct {
	Plan   string  `json:"plan"`
	Cycles []Cycle `json:"cycles"`
}

Ledger is plans/<plan>/comment-pass.json: every verdict the pass has recorded, in order, so verify can tell a kept comment from a new one without a mark in the code.

type Manifest

type Manifest struct {
	Plan  string      `json:"plan"`
	Base  string      `json:"base"`
	Files []FileEntry `json:"files"`
}

Manifest is candidates.json.

type Pass

type Pass struct {
	Root     string
	Plan     string
	Run      RunFunc
	FormatTS FormatTSFunc
	Now      func() time.Time
	Stdout   io.Writer
}

Pass is one invocation's configuration. Zero seams are replaced by New.

func New

func New(root, plan string, stdout io.Writer) *Pass

New returns a Pass wired to the real git, Biome and clock.

func (*Pass) Apply

func (p *Pass) Apply(ctx context.Context, verdictsPath, candidatesPath string, cycle int, message string) error

Apply reconstructs every stripped file from its snapshot minus the dropped spans, records the cycle in the ledger and commits by pathspec. It refuses, before writing, a verdict set that does not account for every candidate exactly once and a tree that moved since strip.

func (*Pass) Drop

func (p *Pass) Drop(ctx context.Context, refs []string, cycle int, message string) error

Drop removes the comment block containing each path:line, records the drops as an orchestrator cycle and commits by pathspec. Every refusal is collected before any write.

func (*Pass) Strip

func (p *Pass) Strip(ctx context.Context, outDir string, all bool) error

Strip collects the branch's candidate comments, removes them from the tree and writes candidates.json and candidates.md under outDir. Nothing is written when a file would stop parsing or when there are no candidates.

func (*Pass) Verify

func (p *Pass) Verify(ctx context.Context) error

Verify fails on any comment block the branch added whose latest ledger verdict is not keep. With no ledger it passes only when the branch added no comment at all.

type RunFunc

type RunFunc func(ctx context.Context, dir, name string, args ...string) (stdout, stderr []byte, err error)

RunFunc is the injectable subprocess seam (docs/conventions.md §Testing).

type Span

type Span struct {
	Start   int    `json:"start"`
	End     int    `json:"end"`
	Replace string `json:"replace,omitempty"`
}

Span is a half-open byte range in the original file; Replace is what removal leaves (one space when code sits on both sides of a segment).

type Verdicts

type Verdicts struct {
	Keep []KeepVerdict `json:"keep"`
	Drop []string      `json:"drop"`
}

Verdicts is the judge's output: every candidate id exactly once.