gate

Documentation

Index

• Variables
• func BuildGatedBody(content string, opts ...Option) string
• func BuildGatedBodyKey(key, content string, opts ...Option) string
• func CheckStalenessTokens(res ScanResult, durSeconds int64) error
• func EndMarker(section string, opts ...Option) string
• func RegisterCommentStyle(ext string, style CommentStyle)
• func RemoveSection(filePath, key string, opts ...Option) error
• func StartMarker(section string, opts ...Option) string
• func UpdateMultiple(filePath string, sections map[string]string, opts ...Option) error
• func UpdateSingle(filePath, sectionContent string, opts ...Option) error
• type CommentStyle
  • func DetectStyleFromExtension(path string) CommentStyle
• type FeatureTokens
• type Option
  • func WithBlankLineBefore() Option
  • func WithKey(k string) Option
  • func WithStyle(cs CommentStyle) Option
  • func WithTokens(start, end string) Option
• type Options
  • func DefaultOptions() Options
• type RequirementTokens
• type ScanResult
• type Scanner
  • func NewScanner(opts ...ScannerOption) *Scanner
  • func (s *Scanner) ScanRepository(root string) (ScanResult, error)
• type ScannerOption
  • func WithNoPromotion() ScannerOption
  • func WithSkipDirs(dirs ...string) ScannerOption
• type SummaryTokens

Variables

var DefaultCommentStyles = map[string]CommentStyle{
	".go":    {LinePrefix: "//"},
	".js":    {LinePrefix: "//"},
	".ts":    {LinePrefix: "//"},
	".tsx":   {LinePrefix: "//"},
	".jsx":   {LinePrefix: "//"},
	".java":  {LinePrefix: "//"},
	".c":     {LinePrefix: "//"},
	".h":     {LinePrefix: "//"},
	".cpp":   {LinePrefix: "//"},
	".rs":    {LinePrefix: "//"},
	".swift": {LinePrefix: "//"},
	".cs":    {LinePrefix: "//"},
	".zig":   {LinePrefix: "//"},
	".py":    {LinePrefix: "#"},
	".sh":    {LinePrefix: "#"},
	".rb":    {LinePrefix: "#"},
	".yml":   {LinePrefix: "#"},
	".yaml":  {LinePrefix: "#"},
	".toml":  {LinePrefix: "#"},
	".env":   {LinePrefix: "#"},
	".sql":   {LinePrefix: "--"},
	".html":  {LinePrefix: "<!--", BlockEnd: "-->", Space: true},
	".md":    {LinePrefix: "<!--", BlockEnd: "-->", Space: true},
	".xml":   {LinePrefix: "<!--", BlockEnd: "-->", Space: true},
}

Global registry for comment styles overrideable at runtime.

Functions

func BuildGatedBody

func BuildGatedBody(content string, opts ...Option) string

BuildGatedBody returns a gated body snippet (unnamed section) with start/end markers surrounding the provided content. Newlines are normalized so the snippet always ends with a trailing newline. The content is placed exactly between markers. Example (markdown): <!-- CANARY:START -->\n<content>\n<!-- CANARY:END -->\n

func BuildGatedBodyKey

func BuildGatedBodyKey(key, content string, opts ...Option) string

BuildGatedBodyKey returns a gated body snippet for a keyed section. Example (markdown): <!-- CANARY:mykey:START -->\n<content>\n<!-- CANARY:mykey:END -->\n

func CheckStalenessTokens

func CheckStalenessTokens(res ScanResult, durSeconds int64) error

CheckStalenessTokens validates staleness directly on ScanResult.

func EndMarker

func EndMarker(section string, opts ...Option) string

EndMarker returns the end marker string for a keyed or unnamed section given options.

func RegisterCommentStyle

func RegisterCommentStyle(ext string, style CommentStyle)

RegisterCommentStyle allows external code to override or add a comment style for extension.

func RemoveSection

func RemoveSection(filePath, key string, opts ...Option) error

RemoveSection removes a keyed section.

func StartMarker

func StartMarker(section string, opts ...Option) string

StartMarker returns the start marker string for a keyed or unnamed section given options.

func UpdateMultiple

func UpdateMultiple(filePath string, sections map[string]string, opts ...Option) error

UpdateMultiple updates or inserts multiple keyed sections.

func UpdateSingle

func UpdateSingle(filePath, sectionContent string, opts ...Option) error

UpdateSingle updates or inserts one gated section in filePath.

Types

type CommentStyle

type CommentStyle struct {
	// LinePrefix denotes a single-line comment marker (e.g. "//", "#", "--").
	LinePrefix string
	// BlockStart and BlockEnd denote multi-line comment delimiters (e.g. "/*" and "*/").
	BlockStart string
	BlockEnd   string
	// Optional space insertion between delimiters and content for readability.
	Space bool
}

CommentStyle describes how comments are represented for a language/file type. Either single-line (LinePrefix) or multi-line (BlockStart/BlockEnd) or both may be set.

func DetectStyleFromExtension

func DetectStyleFromExtension(path string) CommentStyle

DetectStyleFromExtension returns a reasonable default style based on file extension.

type FeatureTokens

type FeatureTokens struct {
	Feature string
	Aspect  string
	Status  string
	Files   []string
	Tests   []string
	Benches []string
	Owner   string
	Updated string
}

FeatureTokens describes one feature/aspect/status token aggregation.

type Option

type Option func(*Options)

Option functional option.

func WithBlankLineBefore

func WithBlankLineBefore() Option

WithBlankLineBefore enables blank line insertion.

func WithKey

func WithKey(k string) Option

WithKey sets gating key.

func WithStyle

func WithStyle(cs CommentStyle) Option

WithStyle sets the comment style.

func WithTokens

func WithTokens(start, end string) Option

WithTokens sets start/end tokens.

type Options

type Options struct {
	Key        string // The logical gating namespace, e.g. "CANARY"
	Style      CommentStyle
	StartToken string // e.g. "START"
	EndToken   string // e.g. "END"
	// If true, enforce blank line preceding an appended section.
	EnsureBlankBefore bool
}

Options configures gating behavior.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns a baseline configuration targeting HTML-style comments used in markdown.

type RequirementTokens

type RequirementTokens struct {
	ID       string
	Features []FeatureTokens
}

RequirementTokens groups feature tokens by requirement ID.

type ScanResult

type ScanResult struct {
	Requirements []RequirementTokens
	Summary      SummaryTokens
}

ScanResult represents the generic scan output independent of root package types.

type Scanner

type Scanner struct {
	// contains filtered or unexported fields
}

Scanner performs repository scans for CANARY tokens.

func NewScanner

func NewScanner(opts ...ScannerOption) *Scanner

NewScanner returns a configured Scanner.

func (*Scanner) ScanRepository

func (s *Scanner) ScanRepository(root string) (ScanResult, error)

ScanRepository scans root and returns ScanResult.

type ScannerOption

type ScannerOption func(*scannerConfig)

ScannerOption configures Scanner behavior.

func WithNoPromotion

func WithNoPromotion() ScannerOption

WithNoPromotion disables automatic status promotion.

func WithSkipDirs

func WithSkipDirs(dirs ...string) ScannerOption

WithSkipDirs adds directories to skip.

type SummaryTokens

type SummaryTokens struct {
	ByStatus map[string]int
	ByAspect map[string]int
}

SummaryTokens holds aggregate counts.