Documentation
¶
Overview ¶
Package catalogvalidate is the cross-entity graph linter for the catalog repo's `data/` tree. It complements two existing layers:
Per-entity Validate() methods (struct shape + intra-entity rules). These run during manifest.ToX translate or domain Validate() and only see one entity at a time.
JSON Schema generated by huma (structural — required fields, types, regex/length). Runs in editors and catalog CI via check-jsonschema.
catalogvalidate fills the remaining gap: relational and graph-completeness checks across the whole catalog. Examples:
- policy.spec.hostKeys names a HostKey that doesn't exist
- hostkey.spec.policyId names a host-owned Policy whose owner is a different host than hostkey.spec.hostId
- hostBinding.snapshots[] references a snapshot name not in Model.spec.snapshots[]
- duplicate names within a kind
- (warn) Model with zero enabled host bindings — won't surface
- (warn) HostKey with no user-owned Policy listing it — relay can't reach the underlying models
The output is a list of Issues, never an early-fail. Catalog CI dumps all at once so authors fix everything in one pass instead of iteratively playing whack-a-mole.
Operates on []manifest.Document so it works at catalog-time (names as refs, ids not yet minted). The seed loader can use the same package to gate writes; control-plane online edits log issues but don't block, matching the snapshot reconciler's forgiving semantics.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Issue ¶
type Issue struct {
Severity Severity
Kind IssueKind
Source Ref
Target Ref // optional — what the source was pointing at when it broke
Message string
}
Issue is one finding from the validator.
func Promote ¶
Promote returns a copy of issues with every warning rewritten to an error. Useful for --strict CLI flags on a release build.
func RunRules ¶
RunRules executes every rule in order against docs and returns the flattened []Issue, sorted deterministically. Rules whose Name appears in skip are silently excluded.
Rule.Severity is the "default" severity used in --list output and documentation; rule Check functions set per-issue severity explicitly. CLI flags like --strict can post-process the result (promote all warnings to errors) without touching this function.
func ValidateGraph ¶
ValidateGraph runs every cross-entity check over docs and returns the findings, sorted deterministically (by severity then source). Empty slice means the catalog is graph-complete.
type IssueKind ¶
type IssueKind string
IssueKind is a coarse-grained classification of what went wrong. The human Message field carries the specifics.
const ( KindRefMissing IssueKind = "ref_missing" KindOwnerMismatch IssueKind = "owner_mismatch" KindSnapshotMissing IssueKind = "snapshot_missing" KindDuplicateName IssueKind = "duplicate_name" KindOrphan IssueKind = "orphan" KindIncomplete IssueKind = "incomplete" KindInvariant IssueKind = "invariant" )
type Ref ¶
Ref points at one location in the catalog: a kind + name, plus an optional field path for sub-locations.
type Rule ¶
type Rule struct {
Name string
Description string
Severity Severity
Check func([]manifest.Document) []Issue
}
Rule is a named, documented check function. Catalog repos (like wyolet/relay-catalog) declare their curation conventions as a []Rule slice and pass it to RunRules. ValidateGraph is the schema-generic counterpart; Rules layer on catalog-specific data conventions.
Conventions for authoring a Rule:
- Name is a stable kebab-case id ("ollama-source-tag"). It's the handle for --skip flags, ignore files, and bug reports — don't rename without a deprecation note.
- Description is a single sentence summarizing the rule. Renders in --list output and (eventually) auto-generated docs.
- Severity is the default; CLI flags like --strict can override. Individual issues emitted by Check may set their own severity to downgrade or upgrade ad-hoc.
- Check is pure — no IO, no panics. Re-entrant; called in iteration order of the rules slice.
type Severity ¶
type Severity int
Severity categorizes how seriously to treat an Issue.
const ( // SeverityError is a graph-integrity problem the catalog cannot ship // with. Examples: unresolvable ref, duplicate name within a kind. SeverityError Severity = iota // SeverityWarning is a curation hint, not a correctness break. The // catalog will load and run, but something is probably misconfigured. // Examples: orphan models, dangling hostkeys. SeverityWarning )
Source Files