file

Documentation

Overview

Package file is the lossless CODEOWNERS file model.

Parsing preserves every byte: Parse followed by Bytes is always byte-identical (INV-5). Mutation is restricted to the four primitives the writer rules allow: amend a line's owner list, insert a new line, delete a line (solely for R-6's `inherit` policy), and replace an INVALID line with its repaired text (solely for lint's owner-spacing fix, which is the one edit no rule-level primitive can express). Nothing here reorders lines.

Invalid lines are retained, reported, and skipped during resolution, matching GitHub's current per-line-skip semantics.

Index

• func IsEmailOwner(tok string) bool
• func PatternToken(raw string) string
• func SplitOwnerRegion(raw string) (head, owners string, ok bool)
• func ValidOwnerToken(tok string) bool
• type File
  • func Parse(content []byte) *File
  • func (f *File) Bytes() []byte
  • func (f *File) DeleteLine(i int)
  • func (f *File) InsertRule(i int, patternText string, owners []string) *Rule
  • func (f *File) InvalidLines() []*Line
  • func (f *File) LineText(i int) string
  • func (f *File) ReplaceLine(i int, raw string) *Line
  • func (f *File) Rules() []*Rule
  • func (f *File) SetOwners(i int, owners []string)
  • func (f *File) Size() int
• type Line
• type LineKind
  • func (k LineKind) String() string
• type Rule
  • func (r *Rule) OwnersCopy() []string
• type SyntaxError

Functions

func IsEmailOwner

func IsEmailOwner(tok string) bool

IsEmailOwner reports whether a valid owner token is an email owner (R-13).

func PatternToken

func PatternToken(raw string) string

PatternToken returns the pattern token of a raw line — the bytes that decide which files it governs — or "" for a blank or comment line. Escape-aware, so a pattern ending in an escaped space comes back whole.

Exported alongside SplitOwnerRegion and for the same reason: an INVALID line has no Rule, so a repair has no other way to ask what pattern it started with, and comparing against a locally re-derived one would compare a repair to its own arithmetic.

func SplitOwnerRegion

func SplitOwnerRegion(raw string) (head, owners string, ok bool)

SplitOwnerRegion splits a raw line into its head — leading whitespace, the pattern token, and the whitespace separating pattern from owners — and the owner region that follows. ok is false for blank and comment lines, which have no pattern token at all.

Exported because an INVALID line has no Rule to interrogate: it never got past parseLine's owner loop, so PatternText, prefix and Owners do not exist for it. Repairing such a line (lint's owner-spacing fix) needs exactly the split parseLine performs, and reimplementing the escape-aware pattern scan elsewhere would let the two drift on the one input that matters — a pattern ending in an escaped space.

func ValidOwnerToken

func ValidOwnerToken(tok string) bool

ValidOwnerToken reports whether tok is a syntactically valid owner: @username, @org/team-name, or an email address.

Types

type File

type File struct {
	Lines []*Line
}

File is a parsed CODEOWNERS file.

func Parse

func Parse(content []byte) *File

Parse parses CODEOWNERS content. It never fails: unparseable lines become LineInvalid with a SyntaxError.

func (*File) Bytes

func (f *File) Bytes() []byte

Bytes serializes the file. Untouched lines are emitted byte-identically.

func (*File) DeleteLine

func (f *File) DeleteLine(i int)

DeleteLine removes line i. Exists solely for R-6's `inherit` policy.

func (*File) InsertRule

func (f *File) InsertRule(i int, patternText string, owners []string) *Rule

InsertRule inserts a new rule line at index i (existing line i shifts down). The new line adopts the file's newline style. If the current final line lacks a trailing newline and the insertion lands after it, that line gains one — the only byte change ever made to an untouched line.

func (*File) InvalidLines

func (f *File) InvalidLines() []*Line

InvalidLines returns the lines that failed to parse.

func (*File) LineText

func (f *File) LineText(i int) string

LineText returns the current text of line i without its EOL — original bytes if untouched, rendered text if amended.

func (*File) ReplaceLine

func (f *File) ReplaceLine(i int, raw string) *Line

ReplaceLine replaces line i with raw, re-parsed, and returns the new line.

It is the only primitive that can reach an INVALID line. Such a line has no Rule, so SetOwners cannot touch it, and DeleteLine would throw away a rule somebody wrote and believes is in force — neither is a repair. Its sole caller is lint's owner-spacing fix, which hands back the same line with whitespace removed from inside an @handle.

The replacement text is emitted VERBATIM (the line is left clean, not dirty): raw is already the exact bytes intended, and re-rendering it from the parsed rule would collapse whatever column alignment the file uses. The original EOL is preserved, so a repair never changes the file's line endings.

func (*File) Rules

func (f *File) Rules() []*Rule

Rules returns the valid rules in file order, with LineIndex set.

func (*File) SetOwners

func (f *File) SetOwners(i int, owners []string)

SetOwners amends the owner list of the rule at line index i (R-1: amend in place, never reorder).

func (*File) Size

func (f *File) Size() int

Size returns the serialized byte size (R-9, S-4).

type Line

type Line struct {
	Raw  string // original text, without EOL
	EOL  string // "\n", "\r\n", or "" (final line without newline)
	Kind LineKind
	Rule *Rule
	Err  *SyntaxError
	// contains filtered or unexported fields
}

Line is one physical line of the file.

type LineKind

type LineKind int

LineKind classifies a parsed line.

const (
	LineBlank LineKind = iota
	LineComment
	LineRule
	LineInvalid
)

func (LineKind) String

func (k LineKind) String() string

type Rule

type Rule struct {
	PatternText string
	Pattern     *pattern.Pattern
	Owners      []string
	LineIndex   int // index into File.Lines
	// contains filtered or unexported fields
}

Rule is a valid pattern line.

func (*Rule) OwnersCopy

func (r *Rule) OwnersCopy() []string

OwnersCopy returns a defensive copy of the rule's owner list (non-nil).

type SyntaxError

type SyntaxError struct {
	Kind    string `json:"kind"`
	Message string `json:"message"`
	Line    int    `json:"line"` // 1-based
	Source  string `json:"source"`
}

SyntaxError describes why a line is invalid. Kind vocabulary matches GitHub's codeowners/errors API: "Invalid pattern", "Invalid owner".