domain

package
v0.28.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package domain holds the routing domain's contracts: the ports, DTOs, enums, constants, and pure validation for resolving a repository (and a PR's changed files) to the Slack channel(s) and behavioural config that apply, across the global/org/repo tiers and monorepo path rules.

It depends only on the standard library, the shared kernel, and the YAML codec used to decode the mappings section of config.yaml onto these types (transition debt: the wire-decoding lives on the domain types until a later phase splits wire types from domain types). It never imports application, infrastructure, or a platform client (store/slack/github).

Index

Constants

View Source
const AtTimeLayout = "15:04"

AtTimeLayout is the `at:` time format: 24-hour HH:MM.

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, in the configured digest timezone (default UTC; see DigestConfig.Timezone).

View Source
const HourlyCronSpec = "0 * * * *"

HourlyCronSpec is the cron spec of the hourly schedule mode.

View Source
const WildcardKey = "*"

WildcardKey is the org-level tier key (the literal "*"): it both supplies defaults that explicit repo tiers inherit and matches any repo not named explicitly.

Variables

View Source
var ErrNotFound = errors.New("store: not found")

ErrNotFound is returned when a repository resolves to no mapping. It is the routing provider's port-contract sentinel. The message string is retained verbatim ("store: not found") so store.ErrNotFound can alias this value during the migration without changing any error text or errors.Is behaviour.

Functions

func IsChannelID added in v0.25.0

func IsChannelID(value string) bool

IsChannelID reports whether value is a well-formed Slack channel id.

Types

type ChangedFilesReader

type ChangedFilesReader interface {
	ListPullRequestFiles(ctx context.Context, owner, repo string, number int) ([]string, error)
}

ChangedFilesReader fetches the repo-relative paths a PR touches. The GitHub client satisfies it.

type ChannelSpec added in v0.24.0

type ChannelSpec struct {
	Channel         string
	Mentions        []string
	MentionsPresent bool
}

ChannelSpec is one entry in a tier's or path rule's `channels:` list: a Slack channel and the mentions to ping there. Mentions carry the same tri-state as a single tier (MentionsPresent distinguishes an absent key — which defaults to ChannelMention — from an explicit empty list that pings nobody).

type Defaults

type Defaults struct {
	Reactions        Reactions
	IgnoreAIReviews  bool
	DependabotFormat bool
	DeleteOnClose    bool
	// GitProvider is the deployment's single git_provider; the Provider stamps it
	// on every entry so it hashes into the lock (see Entry.Provider).
	GitProvider kernel.Provider
}

Defaults is the global tier: the config.yaml top-level behavioral settings that per-repo tiers override.

type DigestConfig

type DigestConfig struct {
	Enabled  bool
	Schedule string
	Timezone string
	Country  string
}

DigestConfig is the `digest:` section: a scheduled reminder that lists open PRs nobody has touched since the previous day. The global section is optional and the feature is opt-in, so an absent section (or one without `enabled: true`) behaves like `{enabled: false}` with the default schedule. Per-repo tiers reuse this type to override Enabled/Schedule.

Timezone and Country are global-only — the server runs a single cron clock and serves a single team calendar, so both belong on the global section and are rejected on a per-repo tier. An empty Timezone means the default (UTC); config.Load resolves it to a *time.Location and fails fast on an invalid zone. An empty Country means no holiday table: weekends are still skipped, but public holidays are not.

type Entry

type Entry struct {
	Org      string
	Repo     string // empty when Wildcard is true
	Wildcard bool
	Channel  string
	Mentions []string
	// ExtraChannels are the distinct channels a repo can post to beyond its
	// primary Channel — extra base-list channels plus per-path channels (sorted,
	// deduped). They feed both validation (bot membership) and the entry hash, so
	// adding or repointing one re-triggers validation. Always empty for a wildcard
	// entry unless the org/* tier itself uses a channels: list.
	ExtraChannels []string
	// Provider is the deployment's git_provider (e.g. "github"). It hashes into
	// every entry so flipping the provider — under which the same org/repo names
	// point at different remote objects — revalidates the whole lock.
	Provider kernel.Provider
	// DeleteOnClose is the entry's resolved cleanup.delete_on_close. It hashes
	// into the entry because it adds required Slack scopes; omitted when false so
	// existing lock hashes stay valid.
	DeleteOnClose bool
}

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.

type NotificationStrategy added in v0.27.0

type NotificationStrategy string

NotificationStrategy decides when a PR event reaches Slack.

const (
	// StrategyPerEvent posts or updates one Slack message per PR as each event
	// arrives. It is the default when no tier sets a strategy.
	StrategyPerEvent NotificationStrategy = "per-event"
	// StrategyScheduled queues new PRs and posts one list message per channel
	// on the tier's schedule.
	StrategyScheduled NotificationStrategy = "scheduled"
)

type NotificationsConfig added in v0.27.0

type NotificationsConfig struct {
	Strategy NotificationStrategy
	Mode     ScheduleMode
	At       []TimeOfDay
	Cron     []string
}

NotificationsConfig is a tier's `notifications:` block. The per-event strategy (also the zero value) posts as each event arrives; the scheduled strategy queues new PRs and sends one list per channel at the times its Mode describes. Send times run in the digest timezone.

func (NotificationsConfig) Scheduled added in v0.27.0

func (c NotificationsConfig) Scheduled() bool

Scheduled reports whether PR events are queued for a scheduled send.

func (NotificationsConfig) Specs added in v0.27.0

func (c NotificationsConfig) Specs() []string

Specs returns the cron specs the scheduled strategy sends on, or nil for the per-event strategy.

type Org

type Org map[string]RepoConfig

Org maps each repo name (or the literal "*") to its tier config. The "*" key is the org-level tier: it both supplies defaults that explicit repo tiers inherit and matches any repo not named explicitly.

type PathRule

type PathRule struct {
	Dir             string
	Channel         string
	Mentions        []string
	MentionsPresent bool
	// Channels is the path rule's `channels:` fan-out list. Mutually exclusive
	// with Channel/Mentions (enforced at decode); nil means the single Channel
	// form. List entries default absent mentions to ChannelMention.
	Channels []ChannelSpec
}

PathRule is one entry in a repo tier's `paths:` block: a normalized directory and the routing applied to files under it. Channel/Mentions carry the same tri-state inheritance as a repo tier (empty Channel inherits; MentionsPresent distinguishes absent from an explicit empty list).

type Reactions

type Reactions struct {
	Enabled       bool
	NewPR         string
	MergedPR      string
	ClosedPR      string
	Approved      string
	Commented     string
	RequestChange string
	BotReview     string
}

Reactions is the resolved per-repo reaction-emoji set (Slack emoji names without colons). Enabled gates whether close/review reactions are added at all. Empty BotReview disables the bot-reviewer marker.

type ReactionsOverride

type ReactionsOverride struct {
	Enabled       *bool
	NewPR         *string
	MergedPR      *string
	ClosedPR      *string
	Approved      *string
	Commented     *string
	RequestChange *string
	BotReview     *string
}

ReactionsOverride is a tier's optional reaction overrides; each nil field inherits from a less-specific tier (org/* then the global config.yaml set).

type RepoConfig

type RepoConfig struct {
	Channel         string
	Mentions        []string
	MentionsPresent bool

	Reactions        *ReactionsOverride
	IgnoreAIReviews  *bool
	DependabotFormat *bool
	DeleteOnClose    *bool
	Digest           *DigestConfig
	// Notifications is the tier's `notifications:` block. It is atomic: the
	// most specific tier that sets it wins whole, so a half-set schedule
	// cannot be inherited. Nil inherits.
	Notifications *NotificationsConfig

	// Paths is the optional per-directory routing for a monorepo, in
	// declaration order (order is significant for tie-breaking). Only valid on
	// a named repo tier — ValidateMappings rejects it on the "*" tier.
	Paths []PathRule

	// Channels is the tier's `channels:` fan-out list (unconditional multi-channel
	// base). Mutually exclusive with Channel/Mentions — exactly one form is
	// populated per tier, enforced at decode. Nil means the single Channel form.
	Channels []ChannelSpec
}

RepoConfig is one tier (org/repo or org/*). Phase A carries routing only. An empty Channel means this tier does not set a channel (it inherits). MentionsPresent distinguishes an absent mentions key (inherit) from an explicit empty list (ping nobody).

type RepoMapping

type RepoMapping struct {
	Repository   string
	SlackChannel string
	Mentions     []string
	// Resolved per-repo behavioral config (global config.yaml defaults merged
	// with org/* and org/repo overrides). Formatting-only — not part of
	// validation or the lock.
	Reactions        Reactions
	IgnoreAIReviews  bool
	DependabotFormat bool
	// DeleteOnClose removes the Slack message when the PR is merged or declined
	// instead of updating it with the [Merged]/[Closed] decoration.
	DeleteOnClose bool
	// Notifications is the resolved strategy: per-event, or scheduled with its
	// send times.
	Notifications NotificationsConfig
}

RepoMapping is the value object handlers and validators consume — a GitHub repository routed to a Slack channel with an optional mentions list, and resolved behavioral config (global defaults merged with org/* and org/repo overrides). The source of truth for routing lives in config.yaml's mappings: section (loaded by internal/config / internal/mappings); the type stays here so consumers don't have to know who produced it.

type Resolved

type Resolved struct {
	Channel  string
	Mentions []string
}

Resolved is the effective routing config for one repository after merging the org/repo tier over the org/* tier.

type RoutingProvider

type RoutingProvider interface {
	// Get returns the resolved mapping for "org/repo", or ErrNotFound when no
	// tier matches.
	Get(ctx context.Context, repository string) (RepoMapping, error)
	// RepoHasPathRules reports whether the repository configures a `paths:` block.
	RepoHasPathRules(repository string) bool
	// TargetsForFiles returns the fan-out destinations for a PR touching files.
	TargetsForFiles(repository string, files []string) []Target
	// BaseTargets returns the repository's unconditional base fan-out targets,
	// used when the repo has no path rules or no changed-files reader.
	BaseTargets(repository string) []Target
}

RoutingProvider resolves a repository to its behavioural mapping and, for a monorepo with path rules, the per-channel fan-out targets for a set of changed files. The application-layer provider satisfies it; the per-PR router depends on it.

type ScheduleMode added in v0.27.0

type ScheduleMode string

ScheduleMode is how a scheduled strategy writes its send times.

const (
	// ScheduleModeHourly sends at the top of every hour.
	ScheduleModeHourly ScheduleMode = "hourly"
	// ScheduleModeAt sends once a day at each listed time.
	ScheduleModeAt ScheduleMode = "at"
	// ScheduleModeCron sends on each listed cron spec.
	ScheduleModeCron ScheduleMode = "cron"
)

type Target

type Target struct {
	Channel  string
	Mentions []string
}

Target is one fan-out destination resolved for a PR: a channel and the mentions to ping there. Produced by the mappings resolver, consumed by the open handler.

type TargetResolver

type TargetResolver interface {
	ResolveTargets(ctx context.Context, repository string, prNumber int) (RepoMapping, []Target, error)
}

TargetResolver resolves the per-PR fan-out: the repository's behaviour plus the per-channel targets, layering path rules over the base tier when a changed-files reader is available.

type TimeOfDay added in v0.27.0

type TimeOfDay struct {
	Hour   int
	Minute int
}

TimeOfDay is one `at:` send time.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL