universe

package
v0.0.25 Latest Latest
Warning

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

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

Documentation

Overview

Package universe reads the universe register of spec 18.3 and counts the outcomes of each scope.

The universe is the set of all source items of programming knowledge. Each card of cards/ and each node of nodes/ is a universe item with the outcome card or node, so the register does not repeat them. The files registers/universe/<source>.jsonl hold the other rows: the items that are aliases, sections, merged, on another site, out of scope, not an item, or still pending.

Index

Constants

This section is empty.

Variables

View Source
var Levels = []string{"C0", "C1", "C2"}

Levels are the coverage levels of spec 18.2 that prog coverage measures now. C0 is an item with a node or a card. C1 is a card that passes the R rules. C2 is a node at W2. The G ladder is not built yet, so C2 does not check G1, and the levels C3 to C6 are not measured yet.

View Source
var Outcomes = []string{"node", "card", "alias", "section", "merged", "disambiguation", "elsewhere:algorithm", "elsewhere:math2", "out-of-scope", "not-an-item", "pending"}

Outcomes are the outcomes of spec 18.3. The outcomes node and card come from nodes and cards, but a row may also use them to record a source name that maps to a node or card with another id.

View Source
var Reasons = []string{"not-programming", "product-marketing", "personal", "too-small"}

Reasons are the reason codes of the outcome out-of-scope.

View Source
var Scopes = []string{"languages", "releases", "concepts", "features", "api", "diagnostics", "proposals", "tasks", "patterns", "weaknesses", "tools", "libraries", "formats", "licences", "people", "terms"}

Scopes are the scopes of spec 18.4.

Functions

func CardGate added in v0.0.24

func CardGate(levels []Level) error

CardGate tells if every card of each scope is at C1 or above, the exit criterion of M1 (spec 21). It returns the scopes that fail.

func Gate

func Gate(counts []Count, max float64, strict []string) error

Gate tells if the counts meet the exit criteria of M1 (spec 21): less than max of all items pending, and no pending item in the strict scopes. It returns the reasons when they are not met.

func ReadRules

func ReadRules(root string) (map[string]ScopeRule, error)

ReadRules reads registers/scope-rules.yaml. A missing file gives no rules.

func ScopeOfKind

func ScopeOfKind(kind string) string

ScopeOfKind returns the scope of the nodes and cards of a kind, or "" for a kind that is not a universe item, such as area.

func Targeted

func Targeted(outcome string) bool

Targeted tells if an outcome needs a target that is a node or a card of this site.

Types

type Count

type Count struct {
	Scope     string         `json:"scope"`
	Total     int            `json:"total"`
	Pending   int            `json:"pending"`
	ByOutcome map[string]int `json:"by_outcome"`
}

Count holds the outcomes of one scope.

func Report

func Report(c *node.Corpus, rows []Row) []Count

Report counts the items of each scope: the nodes and cards of c by kind, and the rows. A row with the outcome node or card that points to a node or card is not counted again. The last Count has the scope "all".

func (Count) Share

func (n Count) Share() float64

Share is the part of the items of the scope that is pending, from 0 to 1.

type Level added in v0.0.24

type Level struct {
	Scope string `json:"scope"`
	// Cards and Nodes are the counts of cards and nodes of the scope.
	Cards int `json:"cards"`
	Nodes int `json:"nodes"`
	// CardsBelow is the number of cards that do not pass the R rules, so they are at C0.
	CardsBelow int `json:"cards_below_c1"`
	// ByLevel counts the items at each level. An item counts at its highest level only.
	ByLevel map[string]int `json:"by_level"`
	// Failing lists the first cards of the scope that do not pass the R rules, as file:line.
	Failing []string `json:"failing,omitempty"`
}

Level holds the coverage levels of the nodes and cards of one scope.

func Coverage added in v0.0.24

func Coverage(c *node.Corpus, bad func(*node.Card) bool, nodeW func(*node.Node) int) []Level

Coverage gives the coverage level of each card and node of c, by scope. bad tells if a card has a block finding of the R rules. nodeW gives the level of the writing ladder of a node. The last Level has the scope "all".

func (Level) AtLeast added in v0.0.24

func (l Level) AtLeast(level string) int

AtLeast is the number of items of the scope at the level or above.

type Problem

type Problem struct {
	Rule string
	Msg  string
}

Problem is one problem of a row, with the check rule that finds it.

func Problems

func Problems(c *node.Corpus, rules map[string]ScopeRule, r Row) []Problem

Problems returns the problems of one row: U01 for an unknown scope or outcome, U02 for a missing reason or target, U03 for a target that is not a node or card of c, and U04 for a reason too-small without a rule of rules.

type Row

type Row struct {
	// Source is the id of the source, such as pldb or cwe. An empty source takes the name of the file.
	Source string `json:"source,omitempty"`
	// ID is the id of the item in the source, and Name is the name that the source gives it.
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	// Scope is one of Scopes.
	Scope string `json:"scope"`
	// Outcome is one of Outcomes.
	Outcome string `json:"outcome"`
	// Target is the slug of the node or card that the row points to, or the tag on the other site for elsewhere outcomes.
	Target string `json:"target,omitempty"`
	// Reason says why the row has its outcome. Out of scope needs a reason code.
	Reason string `json:"reason,omitempty"`
	// Rule is the id of the rule of registers/scope-rules.yaml for the reason too-small.
	Rule string `json:"rule,omitempty"`

	File string `json:"-"`
	Line int    `json:"-"`
}

Row is one row of registers/universe/<source>.jsonl.

func Read

func Read(root string) ([]Row, []error)

Read reads every registers/universe/*.jsonl file under root. A missing directory gives no rows. Errors are the rows that cannot be read.

type ScopeRule

type ScopeRule struct {
	ID    string `yaml:"id"`
	Scope string `yaml:"scope"`
	Rule  string `yaml:"rule"`
}

ScopeRule is one rule of registers/scope-rules.yaml. A row with the reason too-small names the id of a rule, so that a person approves the rule and not each row.

Jump to

Keyboard shortcuts

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