sources

Documentation

Overview

Package sources resolves requirement-ID prefixes to their origin: a local flatfile series (e.g. CBIN-105) or an external ticket system (JIRA, GitLab, GitHub) configured in .canary/project.yaml under `sources:`. CANARY: REQ=ENG-4322; FEATURE="TicketSources"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_CBIN_201_RegistryPattern; UPDATED=2026-08-28

Index

• type Registry
  • func Default() *Registry
  • func FromProjectConfig(cfg *config.ProjectConfig) *Registry
  • func LoadFromRoot(root string) *Registry
  • func NewRegistry(list []Source) (*Registry, error)
  • func (r *Registry) ClaimPattern() *regexp.Regexp
  • func (r *Registry) DestinationSource() (Source, bool)
  • func (r *Registry) Normalize(id string) string
  • func (r *Registry) Pattern() *regexp.Regexp
  • func (r *Registry) Peers() []config.PeerConfig
  • func (r *Registry) Resolve(id string) (Source, bool)
  • func (r *Registry) SetPeers(peers []config.PeerConfig)
  • func (r *Registry) Sources() []Source
  • func (r *Registry) TicketURL(id string) string
• type Source

Types

type Registry

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

Registry answers ID-shaped questions for a set of sources.

func Default

func Default() *Registry

Default returns the registry used when no sources are configured: the historical CBIN flatfile series.

func FromProjectConfig

func FromProjectConfig(cfg *config.ProjectConfig) *Registry

FromProjectConfig builds a registry from a parsed project config. When the config declares no sources, a flatfile source is synthesized from project.key; if the key is empty or invalid, falls back to Default() (CBIN).

func LoadFromRoot

func LoadFromRoot(root string) *Registry

LoadFromRoot reads .canary/project.yaml under root. Any error falls back to Default() — sources config must never break a scan.

func NewRegistry

func NewRegistry(list []Source) (*Registry, error)

NewRegistry validates the sources and builds the combined ID pattern.

func (*Registry) ClaimPattern

func (r *Registry) ClaimPattern() *regexp.Regexp

ClaimPattern matches "✅ <ID>" gap-analysis claim lines (ID in group 1).

func (*Registry) DestinationSource

func (r *Registry) DestinationSource() (Source, bool)

DestinationSource returns the source that `canary ticket sync` targets when promoting a flatfile requirement (create_issue actions): the source with Destination=true, if one is marked (NewRegistry rejects more than one); otherwise the first non-flatfile source in declaration order. Returns false when no source is marked and only flatfile sources are configured — there is nothing to promote a requirement to. CANARY: REQ=ENG-3958; FEATURE="TicketDestination"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_ENG_3958_DestinationSource_MarkedWins,TestCANARY_ENG_3958_DestinationSource_DefaultFirstNonFlatfile,TestCANARY_ENG_3958_DestinationSource_NoneWhenOnlyFlatfile,TestCANARY_ENG_3958_NewRegistry_DuplicateDestinationError,TestCANARY_ENG_3958_NewRegistry_FlatfileDestinationError; UPDATED=2026-08-29

func (*Registry) Normalize

func (r *Registry) Normalize(id string) string

Normalize zero-pads flatfile IDs to at least 3 digits (CBIN-42 → CBIN-042). External ticket IDs and unknown prefixes are returned verbatim.

func (*Registry) Pattern

func (r *Registry) Pattern() *regexp.Regexp

Pattern matches any configured requirement ID (captured in group 1).

func (*Registry) Peers

func (r *Registry) Peers() []config.PeerConfig

Peers returns the configured peer projects in declaration order.

func (*Registry) Resolve

func (r *Registry) Resolve(id string) (Source, bool)

Resolve returns the source owning id's prefix.

func (*Registry) SetPeers

func (r *Registry) SetPeers(peers []config.PeerConfig)

SetPeers sets the peer projects for this registry (used for testing).

func (*Registry) Sources

func (r *Registry) Sources() []Source

Sources returns the configured sources in declaration order.

func (*Registry) TicketURL

func (r *Registry) TicketURL(id string) string

TicketURL expands the owning source's URL template. Empty when the source is flatfile, unknown, or has no URL configured.

type Source

type Source struct {
	Name string
	Type string // flatfile | jira | github | gitlab
	Key  string // uppercase ID prefix, e.g. "CBIN", "PLAT"
	URL  string // optional template; {id} = full ID, {num} = numeric part

	// API is the ticket system's REST base URL, used by `canary ticket
	// sync` when set (falls back to its own defaults, e.g. env vars,
	// otherwise). Empty for flatfile sources.
	API string
	// StatusMap overrides the default CANARY-status -> remote-status-name
	// mapping (STUB/IMPL/TESTED/BENCHED keys) for this source only.
	StatusMap map[string]string

	// Project is this source's ticket-system project key (e.g. a JIRA
	// project). Optional; empty means this source contributes no project
	// of its own to `canary ticket sync`.
	Project string
	// Destination marks this source as the target for create_issue
	// actions. At most one source may set this — see
	// Registry.DestinationSource.
	Destination bool
}

Source is one configured requirement-ID origin.