normevent

package
v0.56.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package normevent defines forge-neutral NormalizedEvent types for harness CEL dispatch (ADR 0061). Schema: docs/normative/normalized-event/v1/.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeChangeProposalIsFork

func ComputeChangeProposalIsFork(headRepo, baseRepo string) bool

ComputeChangeProposalIsFork reports whether a change proposal is fork-based. Missing head or base repo metadata is treated as fork (fail-closed) so CEL guards like !event.state.change_proposal.is_fork stay trustworthy.

func IsTriageAuthorized added in v0.50.0

func IsTriageAuthorized(role ActorRole) bool

IsTriageAuthorized reports whether actor.role is at or above triage, the default threshold for observation agents (triage, review).

func IsWriteAuthorized

func IsWriteAuthorized(role ActorRole) bool

IsWriteAuthorized reports whether actor.role satisfies ADR 0054 dispatch gate.

Types

type Actor

type Actor struct {
	ID               string    `json:"id"`
	Kind             ActorKind `json:"kind"`
	Role             ActorRole `json:"role"`
	BotRole          string    `json:"bot_role,omitempty"`
	RoleVerified     *bool     `json:"role_verified,omitempty"`
	IsEntityAuthor   bool      `json:"is_entity_author"`
	IsEntityAssignee bool      `json:"is_entity_assignee"`
}

Actor is the user or service account that caused the transition.

BotRole and RoleVerified are the additive ADR 0107 fields. BotRole is the provider-resolved canonical Fullsend role of a recognized bot; it is empty for humans and unrecognized bots. RoleVerified is nil when the adapter has not performed a lookup (legacy input, or the label exception where bot-role lookup is not applicable); for bots, true means the bot-role lookup completed (including a successful no-match) and false means it failed.

IsEntityAuthor and IsEntityAssignee are best-effort routing facts, never authorization: anyone who can open an issue is its author, and anyone who can assign issues can assign themselves. IsEntityAssignee is optional in the v1 schema so producers that predate it stay valid, but it is always serialized here (false when unknown) so a CEL trigger such as `is_entity_author || is_entity_assignee` never reads a missing key.

type ActorKind

type ActorKind string

ActorKind distinguishes humans from bots.

const (
	ActorHuman ActorKind = "human"
	ActorBot   ActorKind = "bot"
)

type ActorRole

type ActorRole string

ActorRole is the effective repository permission level (ADR 0054).

const (
	RoleAdmin    ActorRole = "admin"
	RoleMaintain ActorRole = "maintain"
	RoleWrite    ActorRole = "write"
	RoleTriage   ActorRole = "triage"
	RoleRead     ActorRole = "read"
	RoleNone     ActorRole = "none"
	RoleExternal ActorRole = "external"
)

func MapGitHubPermission

func MapGitHubPermission(roleName string) ActorRole

MapGitHubPermission maps a GitHub base role to ActorRole. The GitHub client resolves custom repository roles to a base role before this mapping; unrecognized values map to RoleNone.

func MapGitLabAccessLevel added in v0.46.0

func MapGitLabAccessLevel(accessLevel int) ActorRole

MapGitLabAccessLevel maps a GitLab project membership access level to the normalized repository permission role used by the authorization contract.

type ChangeProposal

type ChangeProposal struct {
	ID       int    `json:"id"`
	HeadRepo string `json:"head_repo"`
	BaseRepo string `json:"base_repo"`
	HeadRef  string `json:"head_ref"`
	BaseRef  string `json:"base_ref"`
	HeadSHA  string `json:"head_sha,omitempty"`
	AuthorID string `json:"author_id"`
	IsFork   bool   `json:"is_fork"`
}

ChangeProposal carries branch/repo context for PR/MR workloads.

type Comment

type Comment struct {
	ID          string `json:"id,omitempty"`
	ParentID    string `json:"parent_id,omitempty"`
	Command     string `json:"command,omitempty"`
	Body        string `json:"body"`
	Instruction string `json:"instruction,omitempty"`
}

Comment describes a comment_* transition. ID and ParentID are backend-native message ids (ADR 0086): GitHub comment id/node_id and normalized parent_id; Slack ts and thread_ts. For conversation comment events both are required; ParentID is always the thread-root id (equal to ID when this message is the root).

type ConversationCategory added in v0.37.0

type ConversationCategory struct {
	ID     string `json:"id,omitempty"`
	Name   string `json:"name"`
	Slug   string `json:"slug,omitempty"`
	Format string `json:"format,omitempty"`
}

ConversationCategory is the exclusive category of a conversation.

type ConversationState added in v0.37.0

type ConversationState struct {
	Category ConversationCategory `json:"category"`
}

ConversationState is conversation-level metadata (ADR 0086).

type Entity

type Entity struct {
	Kind                 EntityKind            `json:"kind"`
	ID                   int                   `json:"id"`
	Key                  string                `json:"key,omitempty"`
	URL                  string                `json:"url"`
	LinkedChangeProposal *LinkedChangeProposal `json:"linked_change_proposal,omitempty"`
}

Entity is the target work item, change proposal, or conversation.

type EntityKind

type EntityKind string

EntityKind identifies work items, change proposals, or conversations. Threads are not a separate entity kind; reply association uses transition.comment.parent_id (ADR 0086).

const (
	EntityWorkItem       EntityKind = "work_item"
	EntityChangeProposal EntityKind = "change_proposal"
	EntityConversation   EntityKind = "conversation"
)

type Event

type Event struct {
	Repo       string     `json:"repo"`
	Entity     Entity     `json:"entity"`
	Transition Transition `json:"transition"`
	Actor      Actor      `json:"actor"`
	State      State      `json:"state"`
	Source     Source     `json:"source"`
}

Event is a forge-neutral routing input for fullsend dispatch.

func ParseJSON

func ParseJSON(data []byte) (*Event, error)

ParseJSON unmarshals and validates a NormalizedEvent from JSON.

func (*Event) ToMap

func (e *Event) ToMap() (map[string]any, error)

ToMap converts the event to a map for CEL evaluation.

func (*Event) Validate

func (e *Event) Validate() error

Validate checks required fields and cross-field consistency.

type IssueType added in v0.56.0

type IssueType struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	IsSubtask bool   `json:"is_subtask"`
}

IssueType is the current work-item type supplied by the tracker. IDs are stable within an instance; names may be customized or renamed. The field names match issue_type in the normalized-entity v1 contract (normentity.IssueType), not the Jira wire format.

type LabelChange

type LabelChange struct {
	Name   string `json:"name"`
	Action string `json:"action"` // added | removed
}

LabelChange describes a label add/remove transition.

type LinkedChangeProposal

type LinkedChangeProposal struct {
	ID  int    `json:"id"`
	URL string `json:"url"`
}

LinkedChangeProposal links a work item to an associated change proposal.

type Review

type Review struct {
	State      string `json:"state"`
	ReviewerID string `json:"reviewer_id"`
}

Review describes a review_submitted transition.

type Source

type Source struct {
	System    SourceSystem `json:"system"`
	RawType   string       `json:"raw_type"`
	RawAction string       `json:"raw_action,omitempty"`
}

Source describes the native forge event.

type SourceSystem

type SourceSystem string

SourceSystem identifies event provenance.

const (
	SystemGitHub   SourceSystem = "github"
	SystemGitLab   SourceSystem = "gitlab"
	SystemJira     SourceSystem = "jira"
	SystemManual   SourceSystem = "manual"
	SystemSchedule SourceSystem = "schedule"
)

type State

type State struct {
	IssueType      *IssueType         `json:"issue_type,omitempty"`
	Labels         []string           `json:"labels"`
	ChangeProposal *ChangeProposal    `json:"change_proposal,omitempty"`
	Conversation   *ConversationState `json:"conversation,omitempty"`
}

State is a snapshot of entity metadata at event time.

type Transition

type Transition struct {
	Kind    TransitionKind `json:"kind"`
	Label   *LabelChange   `json:"label,omitempty"`
	Comment *Comment       `json:"comment,omitempty"`
	Review  *Review        `json:"review,omitempty"`
}

Transition describes what changed on the entity.

type TransitionKind

type TransitionKind string

TransitionKind is the semantic lifecycle transition.

const (
	TransitionOpened          TransitionKind = "opened"
	TransitionReopened        TransitionKind = "reopened"
	TransitionEdited          TransitionKind = "edited"
	TransitionSynchronized    TransitionKind = "synchronized"
	TransitionUpdated         TransitionKind = "updated"
	TransitionClosed          TransitionKind = "closed"
	TransitionMerged          TransitionKind = "merged"
	TransitionMarkedReady     TransitionKind = "marked_ready"
	TransitionLabelChanged    TransitionKind = "label_changed"
	TransitionCommentAdded    TransitionKind = "comment_added"
	TransitionCommentEdited   TransitionKind = "comment_edited"
	TransitionCommentDeleted  TransitionKind = "comment_deleted"
	TransitionReviewSubmitted TransitionKind = "review_submitted"
)

Jump to

Keyboard shortcuts

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