mappings

package
v0.17.0 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package mappings owns the declarative repository → Slack-channel configuration: parsing mappings.yaml, the in-memory Provider used at runtime, and the mappings.lock cache that records which entries have been validated. The package replaces the database-backed RepoMappings store.

Index

Constants

View Source 
const ChannelMention = "<!channel>"

ChannelMention is the Slack wire token used when an entry omits the `mentions:` key — operators see `@channel` in Slack.

View Source 
const DefaultDigestSchedule = "0 9 * * *"

DefaultDigestSchedule is the cron spec used when the digest section is absent or omits `schedule`: 9am every morning, server-local time.

View Source 
const LockFileComment = "DO NOT EDIT — regenerated by notifycat on validation"

LockFileComment is the human-facing warning baked into every written lock.

View Source 
const LockVersion = 1

LockVersion is the current lock-file schema version.

Variables

This section is empty.

Functions

func LockPath 

func LockPath(yamlPath string) string

LockPath derives the lock-file path that lives next to the given mappings.yaml. .yaml / .yml extensions are swapped for .lock; any other suffix gets .lock appended.

func WriteLock 

func WriteLock(path string, l Lock) error

WriteLock writes the lock atomically (write to tmp + rename).

Types

type Diff 

type Diff struct {
	Needs []Entry
	Stale []string
}

Diff is the result of DiffEntries: entries needing validation + lock keys that should be dropped on the next write.

func DiffEntries 

func DiffEntries(current []Entry, lock Lock) Diff

DiffEntries compares the current entries against the lock and returns which entries need validation (new or hash-changed) and which lock keys are stale (present in the lock but not in the file).

type DigestConfig added in v0.16.0 

type DigestConfig struct {
	Enabled  bool
	Schedule string
}

DigestConfig is the optional global `digest:` section: a scheduled reminder that lists open PRs nobody has touched since the previous day. It is a global parameter — one schedule for every org/repo, not per-entry. The section is optional and the feature is on by default, so an absent section behaves like `{enabled: true}` with the default schedule.

func (*DigestConfig) UnmarshalYAML added in v0.16.0 

func (d *DigestConfig) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML walks the mapping node by hand (like Org) so we can default Enabled to true — distinguishing a missing `enabled:` key from an explicit `enabled: false` — while keeping KnownFields-style rejection of typos.

type Entry 

type Entry struct {
	Org      string
	Repo     string // empty when Wildcard is true
	Wildcard bool
	Channel  string
	Mentions []string
}

Entry is one validation unit: an explicit (org, repo) pair or an (org, "*") wildcard. Each entry has its own hash in mappings.lock.

func (Entry) Hash 

func (e Entry) Hash() string

Hash is the cache key for an entry: sha256 over canonical JSON of the validation-relevant fields. Mentions are deliberately excluded — they only affect message formatting at Slack-send time, not anything the validator checks (channel membership, bot scopes, webhook events). A mention edit shouldn't invalidate the entry's cache.

func (Entry) Key 

func (e Entry) Key() string

Key returns the lock-file key for the entry: "org/repo" or "org/*".

type File 

type File struct {
	Digest   *DigestConfig  `yaml:"digest"`
	Mappings map[string]Org `yaml:"mappings"`
}

File is the parsed mappings.yaml document.

func Parse 

func Parse(r io.Reader) (File, error)

Parse reads + validates the YAML document. Unknown keys and shape errors are returned as errors (the server fails fast at startup).

`mentions:` is optional: an absent key means "ping @channel"; `mentions: []` means "ping nobody"; `mentions: null` is rejected (ambiguous).

type FileNotFoundError added in v0.7.0 

type FileNotFoundError struct {
	Path string
	Err  error
}

FileNotFoundError is returned by Load when the mappings file cannot be opened.

func (*FileNotFoundError) Error added in v0.7.0 

func (e *FileNotFoundError) Error() string

func (*FileNotFoundError) Unwrap added in v0.7.0 

func (e *FileNotFoundError) Unwrap() error

type Lock 

type Lock struct {
	Comment string               `json:"_comment,omitempty"`
	Version int                  `json:"version"`
	Entries map[string]LockEntry `json:"entries"`
}

Lock is the on-disk validation cache.

func MergeLock 

func MergeLock(old Lock, validated map[string]LockEntry, drop []string) Lock

MergeLock returns a new Lock built from `old` by adding the `validated` entries and dropping the keys in `drop`.

func ReadLock 

func ReadLock(path string) (Lock, error)

ReadLock parses path. A missing file returns an empty Lock with no error. A malformed file returns an empty Lock and an error so the caller can warn and continue.

type LockEntry 

type LockEntry struct {
	SHA256      string    `json:"sha256"`
	ValidatedAt time.Time `json:"validated_at"`
}

LockEntry records the hash and validation timestamp for one entry.

type Org 

type Org struct {
	Channel         string
	Mentions        []string
	MentionsPresent bool
	Repositories    Repositories
}

Org is one organization's mapping: every configured repository in the org shares this channel and mentions list. MentionsPresent distinguishes the absent-key case (fall back to @channel at lookup time) from `mentions: []` (ping nobody).

func (*Org) UnmarshalYAML 

func (o *Org) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML walks the mapping node by hand so we can:

  • distinguish a missing `mentions:` key from `mentions: []`,
  • reject explicit `mentions: null` (ambiguous; operators should remove the key or use `[]`),
  • keep KnownFields-style rejection of unknown keys.

type ParseError added in v0.7.0 

type ParseError struct {
	Path string
	Err  error
}

ParseError is returned by Load when the mappings file cannot be parsed.

func (*ParseError) Error added in v0.7.0 

func (e *ParseError) Error() string

func (*ParseError) Unwrap added in v0.7.0 

func (e *ParseError) Unwrap() error

type Provider 

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

Provider serves repository → mapping lookups from a parsed mappings.yaml. Construct with Load; safe for concurrent reads (no mutation after Load).

func Load 

func Load(path string) (*Provider, error)

Load reads and validates the file at path.

func NewProvider added in v0.17.0 

func NewProvider(m map[string]Org, digest *DigestConfig) *Provider

NewProvider builds a Provider from already-decoded sections (config.yaml's `mappings:` map and `digest:` block), the in-memory counterpart to Load. A nil digest leaves the feature on by default (see Digest).

func (*Provider) Digest added in v0.16.0 

func (p *Provider) Digest() DigestConfig

Digest returns the effective stuck-PR digest configuration. The feature is enabled by default, so an absent `digest:` section yields {Enabled: true, Schedule: DefaultDigestSchedule}. An explicit section may disable it or override the schedule.

func (*Provider) Entries 

func (p *Provider) Entries() []Entry

Entries returns validation units in deterministic order: orgs sorted A→Z, explicit repos within each org sorted A→Z, wildcard entries last per org.

func (*Provider) Get 

func (p *Provider) Get(_ context.Context, repository string) (store.RepoMapping, error)

Get returns the mapping for "org/repo": exact match first, then wildcard on the org. Returns store.ErrNotFound when nothing matches.

type Repositories 

type Repositories struct {
	All  bool
	List []string
}

Repositories is "*" (whole org) XOR a non-empty list of bare repo names. The YAML accepts either shape; the in-memory representation normalizes.

func (*Repositories) UnmarshalYAML 

func (r *Repositories) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML decodes either the wildcard string "*" or a list of repo names. "*" inside a list, an empty list, or any other shape is rejected.

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.