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
GetObjectiveLabels	func(issueLabels []string) []string	Returns the subset of issueLabels that have defined objective values, preserving original order
ValidateLabelExists	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
LoadObjectiveMappingFromConfig	func() *ObjectiveMapping	Loads the mapping from environment, config file, or defaults (see precedence below)

Constants

The package exports named constants for every label and its default value, grouped by priority tier:

Group	Label constants	Value constants
Critical	ObjectiveLabelCritical, ObjectiveLabelP0	ObjectiveValueCritical (100), ObjectiveValueP0 (100)
Security	ObjectiveLabelSecurityFix	ObjectiveValueSecurityFix (70)
Copilot	ObjectiveLabelCopilotOpt	ObjectiveValueCopilotOpt (75)
Bug	ObjectiveLabelBug	ObjectiveValueBug (60)
High	ObjectiveLabelHighPriority, ObjectiveLabelP1	ObjectiveValueHighPriority (35), ObjectiveValueP1 (35)
Safety	ObjectiveLabelTesting, ObjectiveLabelReliability	ObjectiveValueTesting (50), ObjectiveValueReliability (50)
Engine	ObjectiveLabelWorkflow, ObjectiveLabelEngine	ObjectiveValueWorkflow (45), ObjectiveValueEngine (40)
Integration	ObjectiveLabelMCP, ObjectiveLabelActions, ObjectiveLabelCLI	ObjectiveValueMCP (45), ObjectiveValueActions (40), ObjectiveValueCLI (40)
Performance	ObjectiveLabelPerformance	ObjectiveValuePerformance (30)
Medium	ObjectiveLabelMediumPriority, ObjectiveLabelP2	ObjectiveValueMediumPriority (20), ObjectiveValueP2 (20)
Quality	ObjectiveLabelLintMonster	ObjectiveValueLintMonster (25)
Enhancement	ObjectiveLabelEnhancement	ObjectiveValueEnhancement (15)
Dependencies	ObjectiveLabelDependencies	ObjectiveValueDependencies (10)
Low	ObjectiveLabelLowPriority, ObjectiveLabelP3	ObjectiveValueLowPriority (10), ObjectiveValueP3 (10)
Documentation	ObjectiveLabelDocumentation	ObjectiveValueDocumentation (5)
No value	ObjectiveLabelAIGenerated, ObjectiveLabelAIInspected, ObjectiveLabelSmokeCopilot, ObjectiveLabelQuestion, ObjectiveLabelGoodFirstIssue	0

Multi-label logic option constants:

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

Configuration Precedence

LoadObjectiveMappingFromConfig 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.LoadObjectiveMappingFromConfig()

// Score an issue by its labels
score := om.ComputeObjectiveValue([]string{"bug", "high-priority"})
// score == 60  (max of bug=60, high-priority=35)

// Check which labels contributed
objectiveLabels := om.GetObjectiveLabels([]string{"bug", "good first issue"})
// objectiveLabels == ["bug"]

// 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"; it establishes evaluation precedence among matching labels.
• 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 LoadObjectiveMappingFromConfig() *ObjectiveMapping
  • func (om *ObjectiveMapping) ComputeObjectiveValue(issueLabels []string) int
  • func (om *ObjectiveMapping) GetAllLabels() []string
  • func (om *ObjectiveMapping) GetObjectiveLabels(issueLabels []string) []string
  • func (om *ObjectiveMapping) MarshalJSON() ([]byte, error)
  • func (om *ObjectiveMapping) String() string
  • func (om *ObjectiveMapping) ValidateLabelExists(label string) bool

Constants

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

Objective label/value constants used by the objective-mapping feature.

Note: keep these values in sync with DefaultObjectiveMapping (pkg/github/label_objective_mapping.go) and/or the repository-level .github/objective-mapping.json to avoid divergent scoring semantics. These mappings reflect the actual work domains and priorities:

• Safety/Reliability: Safe outputs, testing, reliability = critical
• Core engine: Compilation, parsing, workflow execution = critical
• Integration: MCP tools, GitHub Actions, CLI = important
• Quality: Bug fixes, performance, linting = important
• Enhancement: New features, documentation = valuable but lower impact

To customize these mappings:

1. Create .github/objective-mapping.json in your repository root
2. Set OBJECTIVE_MAPPING_JSON environment variable (JSON string or file path)
3. See specs/objective-mapping-portfolio-reporting.md for configuration details

Critical Priority Labels

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

Safety-Critical Work (safe outputs, test failures)

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 (especially core path)

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)

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

Combination logic options

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 LoadObjectiveMappingFromConfig

func LoadObjectiveMappingFromConfig() *ObjectiveMapping

LoadObjectiveMappingFromConfig 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) GetAllLabels

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

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

func (*ObjectiveMapping) GetObjectiveLabels

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

GetObjectiveLabels 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) 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.

func (*ObjectiveMapping) ValidateLabelExists

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

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