maturity

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: May 18, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package maturity provides types and functions for maturity model management.

Index

Constants

View Source 
const (
	MeasurementTypeQuantitative = "quantitative" // Numeric values only (e.g., 99.9%)
	MeasurementTypeQualitative  = "qualitative"  // State-based only (e.g., "tracked")
	MeasurementTypeHybrid       = "hybrid"       // Both numeric and state (e.g., "tracked" → 99.9%)
)

Measurement type constants for SLIs.

View Source 
const (
	CriterionTypeQuantitative = "quantitative" // Default: numeric comparison
	CriterionTypeQualitative  = "qualitative"  // Binary state tracking
)

Criterion type constants.

View Source 
const (
	StatusNotStarted = "not_started"
	StatusInProgress = "in_progress"
	StatusCompleted  = "completed"
	StatusBlocked    = "blocked"
)

Enabler status constants.

View Source 
const (
	TypeImplementation = "implementation"
	TypeProcess        = "process"
	TypeTraining       = "training"
	TypeTooling        = "tooling"
)

Enabler type constants.

View Source 
const (
	OpGTE          = "gte"    // Greater than or equal
	OpLTE          = "lte"    // Less than or equal
	OpGT           = "gt"     // Greater than
	OpLT           = "lt"     // Less than
	OpEQ           = "eq"     // Equal
	OperatorExists = "exists" // Qualitative: metric exists/is tracked
)

Operator constants.

View Source 
const (
	QualStatusTracked     = "tracked"     // Metric is being tracked
	QualStatusImplemented = "implemented" // Control/feature is implemented
	QualStatusDefined     = "defined"     // Process/policy is defined
	QualStatusDocumented  = "documented"  // Documentation exists
	QualStatusCompliant   = "compliant"   // Meets compliance requirement
	QualStatusEnabled     = "enabled"     // Feature/capability is enabled
	QualStatusNotTracked  = "not_tracked" // Not yet being tracked
	QualStatusPartial     = "partial"     // Partially implemented
	QualStatusPlanned     = "planned"     // Planned but not started
)

Qualitative status constants for criteria.

View Source 
const (
	LevelNameReactive   = "Reactive"
	LevelNameBasic      = "Basic"
	LevelNameDefined    = "Defined"
	LevelNameManaged    = "Managed"
	LevelNameOptimizing = "Optimizing"
)

Level name constants.

View Source 
const (
	CategoryGovern   = "govern"
	CategoryIdentify = "identify"
	CategoryProtect  = "protect"
	CategoryDetect   = "detect"
	CategoryRespond  = "respond"
	CategoryRecover  = "recover"
)

NIST CSF 2.0 canonical category order.

View Source 
const (
	TagAI                      = "ai"                       // AI/ML-specific security
	TagShiftLeft               = "shift-left"               // Design/build-time controls
	TagSupplyChain             = "supply-chain"             // Software supply chain security
	TagRuntimeDefense          = "runtime-defense"          // Production-time protection
	TagVulnerabilityManagement = "vulnerability-management" // Vulnerability handling
	TagIncidentResponse        = "incident-response"        // Incident handling
	TagApplication             = "application"              // Application-layer security
	TagInfrastructure          = "infrastructure"           // Infrastructure security
	TagCompliance              = "compliance"               // Audit and compliance metrics
	TagDetection               = "detection"                // Monitoring and alerting
	TagAutomation              = "automation"               // Automated security controls
)

Recommended SLI tags for consistent classification across maturity models.

Variables

This section is empty.

Functions

func CategorySortWeight 

func CategorySortWeight() map[string]int

CategorySortWeight returns a map of category ID to sort weight. Lower weight = higher priority. Unknown categories get weight 100. Includes common variations (e.g., "detect" and "detection").

func DefaultCategoryOrder 

func DefaultCategoryOrder() []string

DefaultCategoryOrder returns the NIST CSF 2.0 canonical category order.

func DefaultLevelNames 

func DefaultLevelNames() map[int]string

DefaultLevelNames returns the standard M1-M5 level names.

func GenerateMarp 

func GenerateMarp(specFile, outputFile string) error

GenerateMarp is a convenience function to generate Marp from a spec file.

func GenerateSimpleXLSX 

func GenerateSimpleXLSX(specFile, outputFile string) error

GenerateSimpleXLSX generates a simple XLSX report using omniframe. This provides a basic export without conditional styling.

func GenerateXLSX 

func GenerateXLSX(specFile, outputFile string) error

GenerateXLSX is a convenience function to generate XLSX from a spec file.

func IsQualitativeStatusMet 

func IsQualitativeStatusMet(status string) bool

IsQualitativeStatusMet returns whether a qualitative status indicates compliance.

func NormalizeTags 

func NormalizeTags(tags []string) []string

NormalizeTags returns a sorted, deduplicated slice of tags. Invalid tags are excluded with a warning (logged if logger provided).

func OperatorSymbol 

func OperatorSymbol(op string) string

OperatorSymbol returns the symbol for an operator.

func RecommendedTags 

func RecommendedTags() []string

RecommendedTags returns the list of recommended SLI tags.

func ValidateTag 

func ValidateTag(tag string) error

ValidateTag checks if a tag follows the kebab-case convention.

Types

type Category 

type Category struct {
	ID          string   `json:"id"`                    // Category identifier (e.g., "govern", "protect", "detect")
	Name        string   `json:"name,omitempty"`        // Human-readable name
	Description string   `json:"description,omitempty"` // Category description
	SLIOrder    []string `json:"sliOrder,omitempty"`    // Ordered list of SLI IDs within this category
}

Category defines a category for organizing SLIs with custom ordering. When categories are defined, they control the display order in XLSX and dashboards. When absent, NIST CSF 2.0 canonical order is used as the default.

type Criterion 

type Criterion struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// SLI Reference - links to the metric definition with framework mappings
	SLIID string `json:"sliId,omitempty"` // Reference to SLI by ID

	// Inline SLI fields (for simple cases without separate SLI definition)
	Type       string `json:"type,omitempty"`       // "quantitative" (default), "qualitative"
	MetricName string `json:"metricName,omitempty"` // Human-readable metric description
	Unit       string `json:"unit,omitempty"`       // %, days, count, seconds, etc.

	// SLO Definition (target for this level)
	Operator string  `json:"operator"` // gte, lte, gt, lt, eq, exists
	Target   float64 `json:"target"`   // Target value (for quantitative)

	// Qualitative fields
	Status string `json:"status,omitempty"` // For qualitative: tracked, implemented, defined, etc.

	// Framework mappings - DEPRECATED: use SLI.FrameworkMappings instead
	// Kept for backward compatibility; if set, takes precedence over SLI mappings
	FrameworkMappings []FrameworkMapping `json:"frameworkMappings,omitempty"`

	// Assessment (populated during evaluation)
	Current float64 `json:"current,omitempty"` // Current value (for quantitative)
	IsMet   bool    `json:"isMet,omitempty"`   // Calculated: meets target?

	// Weighting
	Weight   float64 `json:"weight,omitempty"`   // Relative importance (default 1.0)
	Required bool    `json:"required,omitempty"` // Must pass for level (default true if omitted)
}

Criterion is a measurable SLO (Service Level Objective) that defines level achievement. It references an SLI and specifies a target threshold for a specific maturity level. Framework mappings are inherited from the referenced SLI.

func (*Criterion) CheckMet 

func (c *Criterion) CheckMet(current float64) bool

CheckMet checks if a criterion is met given a current value. For qualitative criteria, use CheckQualitativeMet instead.

func (*Criterion) CheckQualitativeMet 

func (c *Criterion) CheckQualitativeMet() bool

CheckQualitativeMet checks if a qualitative criterion is met based on its status.

func (*Criterion) CurrentString 

func (c *Criterion) CurrentString() string

CurrentString returns a formatted current value string or status for qualitative.

func (*Criterion) GetCategory 

func (c *Criterion) GetCategory(spec *Spec) string

GetCategory returns the category for this criterion from its SLI.

func (*Criterion) GetFrameworkMappings 

func (c *Criterion) GetFrameworkMappings(spec *Spec) []FrameworkMapping

GetFrameworkMappings returns framework mappings for this criterion. If the criterion has inline mappings, those are returned. Otherwise, mappings are resolved from the referenced SLI.

func (*Criterion) GetLayer 

func (c *Criterion) GetLayer(spec *Spec) string

GetLayer returns the layer for this criterion from its SLI.

func (*Criterion) GetMetricName 

func (c *Criterion) GetMetricName(spec *Spec) string

GetMetricName returns the metric name for this criterion. Resolves from SLI if not set inline.

func (*Criterion) GetSLI 

func (c *Criterion) GetSLI(spec *Spec) *SLI

GetSLI returns the SLI for this criterion from the spec. Returns nil if no SLI is referenced or not found.

func (*Criterion) GetType 

func (c *Criterion) GetType(spec *Spec) string

GetType returns the type for this criterion. Resolves from SLI if not set inline.

func (*Criterion) GetUnit 

func (c *Criterion) GetUnit(spec *Spec) string

GetUnit returns the unit for this criterion. Resolves from SLI if not set inline.

func (*Criterion) IsQualitative 

func (c *Criterion) IsQualitative() bool

IsQualitative returns true if this is a qualitative criterion.

func (*Criterion) IsQualitativeWithSpec 

func (c *Criterion) IsQualitativeWithSpec(spec *Spec) bool

IsQualitativeWithSpec returns true if this is a qualitative criterion, checking both inline type and resolved SLI type.

func (*Criterion) TargetString 

func (c *Criterion) TargetString() string

TargetString returns a formatted target string like ">=95%" or "Tracked" for qualitative.

type DomainModel 

type DomainModel struct {
	Name        string  `json:"name"`
	Description string  `json:"description,omitempty"`
	Owner       string  `json:"owner,omitempty"`
	Levels      []Level `json:"levels"`
}

DomainModel defines maturity levels for a specific domain.

func (*DomainModel) AllCriteria 

func (d *DomainModel) AllCriteria() []Criterion

AllCriteria returns all criteria across all levels for a domain.

func (*DomainModel) AllEnablers 

func (d *DomainModel) AllEnablers() []Enabler

AllEnablers returns all enablers across all levels for a domain.

func (*DomainModel) CriteriaForLevel 

func (d *DomainModel) CriteriaForLevel(level int) []Criterion

CriteriaForLevel returns criteria for a specific level.

func (*DomainModel) EnablersForLevel 

func (d *DomainModel) EnablersForLevel(level int) []Enabler

EnablersForLevel returns enablers for a specific level.

func (*DomainModel) GetLevel 

func (d *DomainModel) GetLevel(level int) (*Level, bool)

GetLevel returns the level definition for a domain.

type Enabler 

type Enabler struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// Classification
	Type  string `json:"type,omitempty"`  // implementation, process, training, tooling
	Layer string `json:"layer,omitempty"` // requirements, code, infra, runtime, adoption, support

	// Effort
	Effort string `json:"effort,omitempty"` // T-shirt size or duration
	Team   string `json:"team,omitempty"`   // Responsible team

	// Tracking
	Status      string   `json:"status,omitempty"`      // not_started, in_progress, completed
	CriteriaIDs []string `json:"criteriaIds,omitempty"` // Which SLOs this enables

	// Dependencies
	DependsOn []string `json:"dependsOn,omitempty"` // Other enabler IDs
}

Enabler is implementation work to achieve criteria.

type FrameworkMapping 

type FrameworkMapping struct {
	Framework   string `json:"framework"`             // Framework identifier (e.g., "NIST_CSF_2", "NIST_800_53")
	Reference   string `json:"reference"`             // Control or function ID (e.g., "PR.DS-1", "AC-2")
	Name        string `json:"name,omitempty"`        // Human-readable control name
	Description string `json:"description,omitempty"` // Control description
	Baseline    string `json:"baseline,omitempty"`    // Required baseline level (e.g., "high", "moderate", "low")
	Version     string `json:"version,omitempty"`     // Framework version (e.g., "2.0", "Rev 5")
}

FrameworkMapping maps a criterion to an external framework control.

type Level 

type Level struct {
	Level       int         `json:"level"` // 1-5
	Name        string      `json:"name"`  // Reactive, Basic, Defined, Managed, Optimizing
	Description string      `json:"description"`
	Criteria    []Criterion `json:"criteria,omitempty"` // SLOs that define the level
	Enablers    []Enabler   `json:"enablers,omitempty"` // Tasks to achieve the level
}

Level defines a maturity level (M1-M5) for a domain.

func (*Level) CalculateLevelProgress 

func (l *Level) CalculateLevelProgress(values map[string]float64, enablerStatus map[string]string) LevelProgress

CalculateLevelProgress calculates progress for a level given current values.

func (*Level) IsLevelAchieved 

func (l *Level) IsLevelAchieved(values map[string]float64) bool

IsLevelAchieved checks if all required criteria for a level are met.

type LevelProgress 

type LevelProgress struct {
	Level           int     `json:"level"`
	CriteriaMet     int     `json:"criteriaMet"`
	CriteriaTotal   int     `json:"criteriaTotal"`
	ProgressPercent float64 `json:"progressPercent"`
	EnablersDone    int     `json:"enablersDone"`
	EnablersTotal   int     `json:"enablersTotal"`
}

LevelProgress tracks progress toward a maturity level.

type MarkdownOptions 

type MarkdownOptions struct {
	Title           string
	Author          string
	Date            string
	IncludeYAMLMeta bool     // Include YAML front matter for Pandoc/MkDocs
	IncludeTOC      bool     // Include table of contents
	ViewType        string   // "domain", "framework", "both"
	IncludeDetails  bool     // Include criterion details
	Frameworks      []string // Filter to specific frameworks (empty = all)
}

MarkdownOptions configures maturity model markdown generation.

func DefaultMarkdownOptions 

func DefaultMarkdownOptions() *MarkdownOptions

DefaultMarkdownOptions returns sensible defaults.

type MarpGenerator 

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

MarpGenerator generates Marp presentations from maturity specs.

func NewMarpGenerator 

func NewMarpGenerator(spec *Spec) *MarpGenerator

NewMarpGenerator creates a new Marp generator.

func (*MarpGenerator) Generate 

func (g *MarpGenerator) Generate() (string, error)

Generate creates the Marp presentation content.

func (*MarpGenerator) SaveAs 

func (g *MarpGenerator) SaveAs(filename string) error

SaveAs saves the presentation to a file.

type QualitativeState 

type QualitativeState struct {
	ID          string `json:"id"`                    // State identifier (e.g., "tracked", "measured")
	Label       string `json:"label"`                 // Human-readable label
	Description string `json:"description,omitempty"` // What this state means
	Order       int    `json:"order"`                 // Progression order (0 = lowest)
}

QualitativeState defines a state in a qualitative progression. Used for SLIs that progress through states like "not tracked" → "tracked" → "measured".

func DefaultQualitativeStates 

func DefaultQualitativeStates() []QualitativeState

DefaultQualitativeStates returns the standard progression of qualitative states.

type SLI 

type SLI struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`

	// Metric definition
	MetricName string `json:"metricName"`     // Human-readable metric description
	Unit       string `json:"unit,omitempty"` // %, days, count, seconds, etc.
	Type       string `json:"type,omitempty"` // DEPRECATED: use MeasurementType instead. "quantitative" (default), "qualitative"

	// Measurement type - how this SLI can be measured
	// "quantitative" (default): numeric values only (e.g., 99.9% availability)
	// "qualitative": state-based only (e.g., "tracked", "measured")
	// "hybrid": supports both quantitative and qualitative (e.g., "tracked" -> "99.9%")
	MeasurementType string `json:"measurementType,omitempty"`

	// Qualitative states - progression from lowest to highest maturity
	// Only applicable when MeasurementType is "qualitative" or "hybrid"
	QualitativeStates []QualitativeState `json:"qualitativeStates,omitempty"`

	// Classification
	Layer    string `json:"layer,omitempty"`    // requirements, code, infra, runtime, adoption, support
	Category string `json:"category,omitempty"` // prevention, detection, response
	SLIType  string `json:"sliType,omitempty"`  // Observability type: availability, latency, error_rate, throughput, saturation, utilization, quality, freshness

	// Tags enable multi-dimensional classification orthogonal to category.
	// Tags should be lowercase kebab-case (e.g., "ai", "supply-chain", "shift-left").
	Tags []string `json:"tags,omitempty"`

	// Framework mappings - defined once on the SLI, inherited by all SLOs
	FrameworkMappings []FrameworkMapping `json:"frameworkMappings,omitempty"`
}

SLI defines a Service Level Indicator (the metric being measured). Framework mappings are defined here since they apply to the metric itself, not to specific targets at different maturity levels.

func (*SLI) GetMeasurementType 

func (s *SLI) GetMeasurementType() string

GetMeasurementType returns the measurement type for this SLI. Falls back to Type field for backward compatibility, then defaults to quantitative.

func (*SLI) GetNormalizedTags 

func (s *SLI) GetNormalizedTags() []string

GetNormalizedTags returns the SLI's tags sorted and deduplicated.

func (*SLI) GetQualitativeStates 

func (s *SLI) GetQualitativeStates() []QualitativeState

GetQualitativeStates returns the qualitative states for this SLI. Returns default states if none are defined.

func (*SLI) IsHybrid 

func (s *SLI) IsHybrid() bool

IsHybrid returns true if this SLI supports both qualitative and quantitative measurement.

func (*SLI) IsQualitativeOnly 

func (s *SLI) IsQualitativeOnly() bool

IsQualitativeOnly returns true if this SLI only supports qualitative measurement.

func (*SLI) IsQuantitativeOnly 

func (s *SLI) IsQuantitativeOnly() bool

IsQuantitativeOnly returns true if this SLI only supports quantitative measurement.

type Spec 

type Spec struct {
	Schema     string                  `json:"$schema,omitempty"`
	Metadata   *SpecMetadata           `json:"metadata,omitempty"`
	Categories []Category              `json:"categories,omitempty"` // Ordered list of categories with SLI ordering
	SLIs       map[string]*SLI         `json:"slis,omitempty"`       // Service Level Indicators with framework mappings
	Domains    map[string]*DomainModel `json:"domains"`
}

Spec defines a complete maturity specification for an organization. It contains maturity models for multiple domains.

NOTE: As of v0.5.0, maturity models should only contain reference data (SLIs, domains, levels, criteria). State tracking (current values, history, targets) should use PRISM Maturity State documents instead. See docs/design/REFACTOR_MATURITY_STATE.md for migration guidance.

func ReadSpecFile 

func ReadSpecFile(filename string) (*Spec, error)

ReadSpecFile reads a maturity spec from a JSON file.

func (*Spec) AllSLIs 

func (s *Spec) AllSLIs() []*SLI

AllSLIs returns all SLIs in the spec.

func (*Spec) GenerateMarkdown 

func (s *Spec) GenerateMarkdown(opts *MarkdownOptions) string

GenerateMarkdown generates a Markdown document from a maturity spec.

func (*Spec) GetCategoryByID 

func (s *Spec) GetCategoryByID(id string) *Category

GetCategoryByID returns a category by its ID, or nil if not found.

func (*Spec) GetCategoryOrder 

func (s *Spec) GetCategoryOrder() []string

GetCategoryOrder returns the ordered list of categories from the spec. If categories are defined, returns them in order. Otherwise, returns NIST CSF default order.

func (*Spec) GetDomain 

func (s *Spec) GetDomain(name string) (*DomainModel, bool)

GetDomain returns the domain model by name.

func (*Spec) GetSLI 

func (s *Spec) GetSLI(id string) *SLI

GetSLI returns an SLI by ID.

func (*Spec) GetSLIOrderForCategory 

func (s *Spec) GetSLIOrderForCategory(categoryID string) []string

GetSLIOrderForCategory returns the SLI order for a category. Returns nil if the category is not found or has no SLI order defined.

func (*Spec) WriteSpecFile 

func (s *Spec) WriteSpecFile(filename string) error

WriteSpecFile writes a maturity spec to a JSON file.

type SpecMetadata 

type SpecMetadata struct {
	Name         string `json:"name,omitempty"`
	Description  string `json:"description,omitempty"`
	Version      string `json:"version,omitempty"`
	Organization string `json:"organization,omitempty"`
	CreatedAt    string `json:"createdAt,omitempty"`
	UpdatedAt    string `json:"updatedAt,omitempty"`
}

SpecMetadata contains metadata about the maturity specification.

type XLSXGenerator 

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

XLSXGenerator generates Excel reports from maturity specs.

func NewXLSXGenerator 

func NewXLSXGenerator(spec *Spec) *XLSXGenerator

NewXLSXGenerator creates a new XLSX generator.

func (*XLSXGenerator) Generate 

func (g *XLSXGenerator) Generate() error

Generate creates the XLSX file with all sheets.

func (*XLSXGenerator) SaveAs 

func (g *XLSXGenerator) SaveAs(filename string) error

SaveAs saves the XLSX file to the specified path.

Source Files

View all Source files

Directories

Path Synopsis
Command-line tool for generating maturity reports.
 Command-line tool for generating maturity reports.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.