github

README

github Package

The github package provides label-based objective value mapping for issue prioritization scoring.

Overview

This package defines how GitHub issue labels are translated into numeric objective values. It supports configurable mapping strategies (max, sum, first) and can load its configuration from an environment variable, a repository config file, or built-in defaults.

Public API

Types

Type	Description
ObjectiveMapping	Defines how GitHub labels map to numeric objective values, including the combination logic for multiple matching labels

ObjectiveMapping Fields

Field	Type	Description
LabelToValue	map[string]int	Maps label names (case-insensitive) to numeric values
MultiLabelLogic	string	How multiple matching labels are combined: "max" (default), "sum", or "first"
PriorityLabels	[]string	Evaluation order when MultiLabelLogic is "first"

Methods on *ObjectiveMapping

Method	Signature	Description
ComputeObjectiveValue	func(issueLabels []string) int	Calculates the numeric value for an issue based on its labels; returns 0 if no labels match or if the receiver is nil
FilterObjectiveLabels	func(issueLabels []string) []string	Returns the subset of issueLabels that have defined objective values, preserving original order
HasObjectiveLabel	func(label string) bool	Reports whether a given label has a defined objective value
GetAllLabels	func() []string	Returns all labels defined in the mapping, sorted alphabetically
MarshalJSON	func() ([]byte, error)	Implements json.Marshaler; produces indented JSON output
String	func() string	Returns a human-readable summary: ObjectiveMapping{labels: N, logic: X, priorities: M}

Functions

Function	Signature	Description
DefaultObjectiveMapping	func() *ObjectiveMapping	Returns the built-in default label-to-value mapping
LoadObjectiveMapping	func() *ObjectiveMapping	Loads the mapping from environment, config file, or defaults (see precedence below)

Constants

The package exports constants for multi-label logic options:

Constant	Value	Description
MultiLabelLogicMax	"max"	Use the highest matching label value (default)
MultiLabelLogicSum	"sum"	Sum all matching label values
MultiLabelLogicFirst	"first"	Use the first match in priority order

For backward compatibility, deprecated exported ObjectiveLabel* and ObjectiveValue* constants are still available for external consumers. Runtime scoring behavior is not derived from those constants.

Default label-to-value entries are provided by DefaultObjectiveMapping():

Label	Value
critical	100
p0	100
security-fix	75
high-priority	50
copilot-opt	50
p1	50
performance	30
medium-priority	25
p2	25
low-priority	10
p3	10
documentation	5

Labels not listed above (for example bug, testing, and reliability) are not part of the default mapping and evaluate to 0 unless provided by configuration.

Configuration Precedence

LoadObjectiveMapping resolves the mapping in this order:

1. OBJECTIVE_MAPPING_JSON environment variable — interpreted first as a raw JSON string; if parsing fails, treated as a file path from which JSON is read.
2. .github/objective-mapping.json — a repository-level override file.
3. Built-in defaults — returned by DefaultObjectiveMapping().

Usage Examples

import "github.com/github/gh-aw/pkg/github"

// Load mapping (env > config file > defaults)
om := github.LoadObjectiveMapping()

// Score an issue by its labels (default mapping: critical=100, high-priority=50, p1=50, ...)
score := om.ComputeObjectiveValue([]string{"critical", "high-priority"})
// score == 100  (max of critical=100, high-priority=50)

// Check which labels contributed
objectiveLabels := om.FilterObjectiveLabels([]string{"critical", "high-priority"})
// objectiveLabels == ["critical", "high-priority"]

// Use the default mapping directly
defaults := github.DefaultObjectiveMapping()
fmt.Println(defaults) // ObjectiveMapping{labels: 12, logic: max, priorities: 7}

Dependencies

Internal:

• github.com/github/gh-aw/pkg/logger — debug logging via logger.New("github:label_objective_mapping")

External:

• None beyond the Go standard library (encoding/json, fmt, os, path/filepath, slices, strings).

Design Notes

• All label comparisons are case-insensitive: labels are normalised with strings.ToLower(strings.TrimSpace(...)) before lookup.
• The default MultiLabelLogic is "max". Callers that do not set this field get max-value semantics automatically.
• PriorityLabels is only consulted when MultiLabelLogic is "first"; the implementation walks the issue's labels in their existing order and returns the value for the first label that also appears in PriorityLabels. If no priority entry matches, it falls back to the first matched value collected from LabelToValue.
• Debug output is controlled by the DEBUG=github:* environment variable and is only emitted when that variable is set.

---

This specification is automatically maintained by the spec-extractor workflow.

Documentation

Index

• Constants
• type ObjectiveMapping
  • func DefaultObjectiveMapping() *ObjectiveMapping
  • func LoadObjectiveMapping() *ObjectiveMapping
  • func (om *ObjectiveMapping) ComputeObjectiveValue(issueLabels []string) int
  • func (om *ObjectiveMapping) FilterObjectiveLabels(issueLabels []string) []string
  • func (om *ObjectiveMapping) GetAllLabels() []string
  • func (om *ObjectiveMapping) HasObjectiveLabel(label string) bool
  • func (om *ObjectiveMapping) MarshalJSON() ([]byte, error)
  • func (om *ObjectiveMapping) String() string

Constants

const (
	MultiLabelLogicMax   = "max"   // Use highest value (default)
	MultiLabelLogicSum   = "sum"   // Add all values
	MultiLabelLogicFirst = "first" // Use first in priority order
)

Multi-label logic options.

const (
	ObjectiveLabelCritical = "critical"
	ObjectiveLabelP0       = "p0"
	ObjectiveValueCritical = 100
	ObjectiveValueP0       = 100
)

Critical Priority Labels.

const (
	ObjectiveLabelTesting     = "testing"
	ObjectiveLabelReliability = "reliability"
	ObjectiveValueTesting     = 50
	ObjectiveValueReliability = 50
)

Safety-Critical Work.

const (
	ObjectiveLabelWorkflow = "workflow"
	ObjectiveLabelEngine   = "engine"
	ObjectiveValueWorkflow = 45
	ObjectiveValueEngine   = 40
)

Core Engine & Compilation.

const (
	ObjectiveLabelMCP     = "mcp"
	ObjectiveLabelActions = "actions"
	ObjectiveLabelCLI     = "cli"
	ObjectiveValueMCP     = 45
	ObjectiveValueActions = 40
	ObjectiveValueCLI     = 40
)

Integration Points.

const (
	ObjectiveLabelBug = "bug"
	ObjectiveValueBug = 60
)

Bug Fixes.

const (
	ObjectiveLabelSecurityFix = "security-fix"
	ObjectiveValueSecurityFix = 70
)

Security.

const (
	ObjectiveLabelCopilotOpt = "copilot-opt"
	ObjectiveValueCopilotOpt = 75
)

Copilot-Specific Optimizations.

const (
	ObjectiveLabelHighPriority = "high-priority"
	ObjectiveLabelP1           = "p1"
	ObjectiveValueHighPriority = 35
	ObjectiveValueP1           = 35
)

High Priority Work.

const (
	ObjectiveLabelLintMonster = "lint-monster"
	ObjectiveValueLintMonster = 25
	ObjectiveLabelPerformance = "performance"
	ObjectiveValuePerformance = 30
)

Code Quality.

const (
	ObjectiveLabelMediumPriority = "medium-priority"
	ObjectiveLabelP2             = "p2"
	ObjectiveValueMediumPriority = 20
	ObjectiveValueP2             = 20
)

Medium Priority Work.

const (
	ObjectiveLabelDependencies = "dependencies"
	ObjectiveValueDependencies = 10
)

Dependency Management.

const (
	ObjectiveLabelLowPriority = "low-priority"
	ObjectiveLabelP3          = "p3"
	ObjectiveValueLowPriority = 10
	ObjectiveValueP3          = 10
)

Low Priority Work.

const (
	ObjectiveLabelEnhancement   = "enhancement"
	ObjectiveValueEnhancement   = 15
	ObjectiveLabelDocumentation = "documentation"
	ObjectiveValueDocumentation = 5
)

Enhancement & Documentation.

const (
	ObjectiveLabelAIGenerated  = "ai-generated"
	ObjectiveValueAIGenerated  = 0
	ObjectiveLabelAIInspected  = "ai-inspected"
	ObjectiveValueAIInspected  = 0
	ObjectiveLabelSmokeCopilot = "smoke-copilot"
	ObjectiveValueSmokeCopilot = 0
)

Workflow/Automation Labels (no objective value).

const (
	ObjectiveLabelQuestion       = "question"
	ObjectiveValueQuestion       = 0
	ObjectiveLabelGoodFirstIssue = "good first issue"
	ObjectiveValueGoodFirstIssue = 0
)

Question & Community Labels (no objective value).

Types

type ObjectiveMapping

type ObjectiveMapping struct {
	// LabelToValue maps label names (case-insensitive) to numeric values.
	// Example: {"high-priority": 50, "copilot-opt": 50, "critical": 100, "p0": 100, "p1": 50}
	LabelToValue map[string]int `json:"label_to_value"`

	// MultiLabelLogic determines how multiple matching labels are combined:
	// "sum" = add all matching label values
	// "max" = take the highest value (default)
	// "first" = use the first match in priority order
	MultiLabelLogic string `json:"multi_label_logic"`

	// PriorityLabels defines evaluation order when logic is "first"
	// Used to establish precedence when multiple labels match
	PriorityLabels []string `json:"priority_labels,omitempty"`
}

ObjectiveMapping defines how GitHub labels map to numeric objective values. This enables any label to be assigned a configurable numeric value, with one central definition place.

func DefaultObjectiveMapping

func DefaultObjectiveMapping() *ObjectiveMapping

DefaultObjectiveMapping returns the built-in default label-to-value mapping.

func LoadObjectiveMapping

func LoadObjectiveMapping() *ObjectiveMapping

LoadObjectiveMapping loads the mapping from environment, config file, or defaults. Precedence: 1. OBJECTIVE_MAPPING_JSON environment variable 2. .github/objective-mapping.json file 3. Built-in defaults

func (*ObjectiveMapping) ComputeObjectiveValue

func (om *ObjectiveMapping) ComputeObjectiveValue(issueLabels []string) int

ComputeObjectiveValue calculates the numeric value for an issue based on its labels. Returns 0 if no labels match or if mapping is nil.

func (*ObjectiveMapping) FilterObjectiveLabels

func (om *ObjectiveMapping) FilterObjectiveLabels(issueLabels []string) []string

FilterObjectiveLabels returns the subset of issue labels that have objective values. Also returns the labels in the order they appear in the issue's label list.

func (*ObjectiveMapping) GetAllLabels

func (om *ObjectiveMapping) GetAllLabels() []string

GetAllLabels returns all labels defined in the mapping (sorted).

func (*ObjectiveMapping) HasObjectiveLabel

func (om *ObjectiveMapping) HasObjectiveLabel(label string) bool

HasObjectiveLabel checks if a given label has a defined objective value.

func (*ObjectiveMapping) MarshalJSON

func (om *ObjectiveMapping) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler to ensure consistent output.

func (*ObjectiveMapping) String

func (om *ObjectiveMapping) String() string

String returns a human-readable summary of the mapping.