commentpass

package
v0.20.5 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 19 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
var ErrRefused = errors.New("refused")

ErrRefused marks a refusal that wrote nothing.

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

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

Functions

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.

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.