spdxkit

package
v0.14.9 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package spdxkit is the single home for SPDX license behavior in the Bomly SDK (ADR-0038 in bomly-cli's dev-docs/adr): expression validation, classification, deprecated-identifier canonicalization, and deterministic LicenseRef minting.

License strings are untrusted input everywhere — they arrive from lockfiles a repository commits and from registry APIs — and the underlying SPDX expression parser panics on some of them ("(((" dereferences a nil operator). Every entry point here contains that and reports the value as one it could not parse, which is what an unparseable license is. No other package may import github.com/github/go-spdx directly; the module's import-boundary test fails when a call site bypasses this package.

spdxkit is a leaf package: it imports go-spdx and the standard library only, never the root SDK package, so both the root package and the helper kits can build on it without an import cycle.

Index

Constants

View Source
const BomlyLicenseRefPrefix = LicenseRefPrefix + "bomly-"

BomlyLicenseRefPrefix marks Bomly-minted license references. The charset of the full reference is restricted to what the SPDX idstring grammar allows. A reference under this prefix is derived from its text (MintLicenseRef), so it is re-minted rather than trusted; a reference under LicenseRefPrefix but not this one was defined by the source document and is preserved as stated.

View Source
const LicenseRefPrefix = "LicenseRef-"

LicenseRefPrefix is the SPDX grammar's marker for a license identifier that is not on the SPDX license list. A document may define its own references under it, so seeing this prefix says the identifier needs accompanying extracted text -- not that Bomly minted it.

Variables

This section is empty.

Functions

func BatchWithinBounds

func BatchWithinBounds(values []string) bool

BatchWithinBounds reports whether a batch of license values fits the package's aggregate parsing limits (member count and total bytes). Callers that invoke classification or validation once per member — rather than through the batch APIs, which enforce this themselves — gate on it first, so a large set of individually short values cannot drive unbounded parser work.

func CanonicalExpression

func CanonicalExpression(expression string) string

CanonicalExpression returns go-spdx's normalized rendering of a license expression with deprecated identifiers replaced by their current names. Valid input may therefore lose redundant parentheses or spacing. Non-SPDX free-text values pass through unchanged — the whole input must validate before any identifier is rewritten, so text that happens to contain a deprecated identifier ("use GPL-2.0 here") is never corrupted.

A valid input always yields a valid result. Valid already refuses a value whose go-spdx rendering go-spdx rejects, so such a value is free text here and comes back unchanged. The checks below keep the promise for the renderings this function produces itself: a rendering is returned only when it validates, and the input -- which did -- otherwise.

func CanonicalIdentifier

func CanonicalIdentifier(value string) (canonical string, ok bool)

CanonicalIdentifier is Identifier plus deprecated-identifier replacement: the one call sites use to get the current canonical spelling of a value that is exactly one license-list entry. A deprecated entry whose replacement is an expression (not a bare identifier) reports the expression; callers that require an identifier check the result with Identifier again or classify it.

func Compose

func Compose(values []string) string

Compose joins several license expressions into one conjunctive expression. A package declaring several licenses is bound by all of them, so they join with AND, and a compound member is parenthesized to keep its own operators from binding across the join.

Each member is normalized through go-spdx to decide whether parentheses are required. Invalid members remain byte-for-byte after trimming, so composing free text still produces an expression that does not parse.

The batch carries the same aggregate bounds as ValidateAll and Satisfies — each member normalization is one parser invocation. An over-count or over-bytes batch still composes, but parenthesization falls back to the whitespace heuristic instead of invoking the parser per member.

func Extract

func Extract(expression string) (licenses []string, err error)

Extract returns the individual license identifiers an expression uses. An unparseable expression returns the parser's error; an expression rejected by a safety limit or parser panic yields nothing and no error.

func Identifier

func Identifier(value string) (string, bool)

Identifier returns the canonical spelling of a value that is exactly one entry in the SPDX license list, and reports whether it is one.

Compound expressions are rejected: an operator ("MIT OR Apache-2.0") is an expression, not a list entry, and the two are not interchangeable in formats that hold identifiers and expressions in separate fields. A trailing "+" does not by itself make a value compound — deprecated entries such as "GPL-2.0+" are list members and resolve here; a plus-suffixed value that is not a list entry ("GPL-2.0-only+", "MIT+") is an or-later expression and is rejected by the lookups. Deprecated identifiers still resolve — they remain list members; CanonicalIdentifier additionally folds them to their current replacements.

func LicenseRefsIn added in v0.7.0

func LicenseRefsIn(expression string) []string

LicenseRefsIn returns the license references an expression names, sorted and deduplicated. It returns nil when the expression names none or cannot be parsed.

The enumeration is the parser's, not a scan for the prefix: a reference is whatever SPDX's grammar says is one, and a substring match would find the prefix inside a quoted or malformed value that is not a reference at all.

The sort is the contract, not a convenience. Extract collects identifiers through a map, so it reports them in an order that varies between runs of the same binary on the same input -- an earlier version of this function promised "the order the parser reports them", which is not an order at all. A caller that indexed the result, or a test that pinned it, would pass locally and fail elsewhere.

func ReplaceLicenseRef added in v0.7.0

func ReplaceLicenseRef(expression, old, replacement string) string

ReplaceLicenseRef rewrites every occurrence of one license reference in an expression, leaving the rest of the expression untouched.

Replacement is boundary-aware. Identifier characters are letters, digits, "." and "-", so a plain substring replacement of "LicenseRef-Custom" would also rewrite the middle of "LicenseRef-Custom2" and silently rename a different license.

func Replacement

func Replacement(deprecatedID string) (replacement string, ok bool)

Replacement returns the current replacement for a deprecated SPDX license identifier, matching case-insensitively through the list's canonical spelling. The replacement may be an expression, not just an identifier — "GPL-2.0-with-classpath-exception" becomes a WITH expression.

func Satisfies

func Satisfies(expression string, allowed []string) (ok bool, err error)

Satisfies reports whether an expression is satisfied by an allowed set. An unparseable expression satisfies nothing and returns the parser's error, or false with no error when the parser could not run at all.

func Valid

func Valid(expression string) bool

Valid reports whether a value within the package's safety limits parses as an SPDX license expression. Unparseable values — free text such as "non-standard", or malformed grouping — report false rather than failing the caller.

"Parses" means go-spdx accepts both the value and its own normalized rendering of it. The library is lenient with some spellings: it accepts "APL-1.0+WITHClAsspAth-eXCeption-2.0", renders it as "APL-1.0+ WITH Classpath-exception-2.0", and rejects that rendering. Such a value has no spelling the library will stand behind, so publishing it as an expression -- as written or as rendered -- writes a license field that a strict consumer, or go-spdx itself, refuses. It is free text instead, which both formats can carry without claiming it is an expression. The parser stays the judge of both spellings; nothing here reads the grammar.

func ValidLicenseRef added in v0.7.0

func ValidLicenseRef(id string) bool

ValidLicenseRef reports whether id is a well-formed SPDX license reference: the LicenseRef- prefix followed by a non-empty idstring, which the SPDX grammar restricts to letters, digits, "." and "-".

This is a publication gate, not a formality. License identifiers arrive from untrusted documents and are written verbatim into an expression field, so a value carrying a space, a quote, or an operator word would either corrupt the emitted document or change what the expression means.

func ValidateAll

func ValidateAll(values []string) (valid bool, invalid []string)

ValidateAll reports whether every value within the package's aggregate and structural safety limits parses as an SPDX license expression, returning the values that do not.

func WithinBounds added in v0.7.0

func WithinBounds(value string) bool

WithinBounds reports whether a value is small and simple enough for this package to parse. Every entry point applies it internally before parsing, so an over-limit value is already refused; it is exported so a caller holding an expression can decline early without keeping a second copy of the limit.

Types

type Class

type Class int

Class is the shape of a raw license value, decided by validating it.

const (
	// ClassFreeText does not parse as SPDX: it carries as text, or as a
	// minted LicenseRef where the format demands an identifier.
	ClassFreeText Class = iota
	// ClassIdentifier is exactly one SPDX license-list entry, deprecated
	// entries included.
	ClassIdentifier
	// ClassExpression parses as an SPDX expression but is not one SPDX
	// license-list identifier. It may be compound or an atomic LicenseRef.
	ClassExpression
)

func Classify

func Classify(value string) Class

Classify decides what a raw license value is by validating it — never by which field carried it (ADR-0035 in bomly-cli's dev-docs/adr). This is the one way a value becomes an identifier, an expression, or free text. Identifier is checked before expression, because a bare identifier also parses as an expression; deprecated identifiers classify as identifiers and canonicalize through CanonicalIdentifier. Empty and blank values are free text.

func (Class) String

func (c Class) String() string

String names the class for logs and tests.

type ExtractedText

type ExtractedText struct {
	// RefID is the minted reference: the prefix plus 32 hex characters.
	// Derived from Text; validated by Valid, repaired by MintLicenseRef.
	RefID string
	// Text is the original license text, unmodified. Authoritative: every
	// other field is recomputable from it.
	Text string
}

ExtractedText pairs a minted license reference with the original text it names, ready for SPDX hasExtractedLicensingInfos and the CycloneDX equivalent (bomly-cli issue #410).

The value is derived, never authored: Text is the authoritative half and RefID is a pure function of it, so the validation gate is MintLicenseRef itself — a value from an untrusted producer is checked with Valid, which re-mints from Text, and an invalid one is repaired by re-minting rather than trusted. Merge class: union keyed by RefID. Two values with the same RefID are interchangeable when valid (same normalized text mints the same reference), duplicates collapse, and a RefID that contradicts its Text is not a conflict to resolve — Text wins and the reference is re-derived.

func MintLicenseRef

func MintLicenseRef(text string) ExtractedText

MintLicenseRef deterministically mints a license reference for a free-text license value: the SHA-256 of the whitespace-normalized text, truncated to 128 bits, hex-encoded, under the bomly LicenseRef prefix. The same text always mints the same reference on every run and machine — hashing keeps minting collision-resistant across components without coordination, and the output uses only characters the SPDX idstring grammar allows. The stored Text keeps the original value untouched; normalization applies to the hash input only, so texts differing merely in whitespace share a reference.

func (ExtractedText) Valid

func (e ExtractedText) Valid() bool

Valid reports whether the reference is the one Text mints — the gate a consumer applies to an ExtractedText it did not mint itself.

Jump to

Keyboard shortcuts

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