check

package
v0.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package check implements compiler-enforced quality gates: static analysis rules over a page's AST and its resolved output (final HTML + JS weight). Built-in rule categories are accessibility (a11y), SEO, and performance (perf). Rules run after a build, so they inspect exactly what would ship. Findings reuse internal/diag for consistent `file:line:col` formatting, and the same rule set backs the `krate check` CLI command. Custom rules can be authored in TypeScript/JavaScript and run inside the embedded QuickJS runtime (see custom.go); no Node is required.

Index

Constants

View Source
const (
	CategoryA11y = "a11y"
	CategorySEO  = "seo"
	CategoryPerf = "perf"
)

Rule categories. Also used as the short prefix in a rule ID (`a11y/img-alt`).

Variables

This section is empty.

Functions

func Counts

func Counts(fs []Finding) (errors, warnings int)

Counts returns the number of error and warning findings.

func Failing

func Failing(fs []Finding, failOn Severity) bool

Failing reports whether any finding meets or exceeds the configured failure threshold. Off never fails.

func Format

func Format(fs []Finding) string

Format renders the report with auto-detected color.

func FormatWith

func FormatWith(fs []Finding, opts FormatOptions) string

FormatWith renders findings grouped by route, aligned by rule ID, with an optional colorized severity marker. Style is a no-op when opts.Color is false so CI logs stay clean.

func KnownRuleIDs

func KnownRuleIDs() []string

KnownRuleIDs returns every built-in rule ID, sorted. Used by docs and diagnostics (e.g. listing valid keys for `checks.ignore`).

func Summary

func Summary(errors, warnings int, opts FormatOptions) string

Summary renders a colorized one-line tally.

Types

type Config

type Config struct {
	// Active is false when checks are disabled entirely.
	Active bool
	// Categories maps a category name ("a11y"/"seo"/"perf") to its severity.
	// Absent categories use the built-in default (all on).
	Categories map[string]Severity
	// Rules maps a full rule ID ("a11y/img-alt") to a severity override.
	Rules map[string]Severity
	// Ignore is the set of rule IDs to suppress.
	Ignore map[string]bool
	// JSBudgetBytes is the per-route client JS budget. 0 disables the rule.
	JSBudgetBytes int
	// FailOn is the minimum severity that makes `krate check` (and a checks-
	// enabled build) exit non-zero.
	FailOn Severity
	// Custom lists paths (relative to Root) to JS/TS modules exporting a
	// `check` rule (see custom.go).
	Custom []string

	// Root and Env are carried to custom (plugin) rules.
	Root string
	Env  map[string]string

	// Routes is the set of known site routes (leading slash; stored both with
	// and without a trailing slash) used by the broken-link rule. Populated by
	// the build pipeline before Run; empty disables the rule.
	Routes map[string]bool
}

Config controls which built-in rules run and how findings are reported. It is built from the `checks` key in krate.config.ts (see FromMap) or from defaults for `krate check` when no config is present.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns an active config with every category enabled and failOn=error. Used by `krate check` when no `checks` config is present.

func FromMap

func FromMap(m map[string]any, root string, env map[string]string) (Config, error)

FromMap builds a Config from the raw `checks` object parsed out of krate.config.ts. Unknown keys are ignored for forward compatibility.

checks: {
  a11y: "error" | "warning" | false,   // category toggle/severity
  seo: true,
  perf: true,
  rules: { "a11y/img-alt": "off" },
  ignore: ["seo/canonical"],
  budget: { js: 100 },                  // KB per route
  failOn: "error" | "warning",
}

type Finding

type Finding struct {
	Rule     string   `json:"rule"`
	Category string   `json:"category"`
	Severity Severity `json:"severity"`
	Route    string   `json:"route,omitempty"`
	File     string   `json:"file,omitempty"`
	Line     int      `json:"line,omitempty"`
	Col      int      `json:"col,omitempty"`
	Message  string   `json:"message"`
	Hint     string   `json:"hint,omitempty"`
}

Finding is one quality-gate violation.

func Run

func Run(cfg Config, pages []Page) ([]Finding, error)

Run evaluates every enabled rule against every page and returns the combined findings, sorted by route then severity (errors first). Custom rules run last.

func (Finding) Diagnostic

func (f Finding) Diagnostic() diag.Diagnostic

Diagnostic renders the finding through the shared compiler diagnostic type, so check output matches parse/build errors.

func (Finding) Error

func (f Finding) Error() string

type FormatOptions

type FormatOptions struct {
	// Color enables ANSI styling. Use DefaultFormatOptions to auto-detect.
	Color bool
}

FormatOptions controls how a findings report is rendered.

func DefaultFormatOptions

func DefaultFormatOptions() FormatOptions

DefaultFormatOptions enables color unless the environment opts out. This matches the rest of the Krate CLI, which always emits ANSI styling; NO_COLOR (or TERM=dumb) disables it for logs and dumb terminals.

type Page

type Page struct {
	// Route is the URL path (e.g. "/blog/hello"). "/" for the site root.
	Route string
	// RelSource is the source file path relative to the project root.
	RelSource string
	// HTML is the final, fully assembled document (head + body, post-SEO
	// injection, post-minify) - exactly what is written to disk.
	HTML string
	// JSBytes is this route's total client JS weight (page hydration + shared
	// runtime chunk), in bytes.
	JSBytes int
	// Program is the page's parsed program. Optional; may be nil for
	// plugin-generated routes.
	Program *ast.Program
}

Page is the unit rules are evaluated against: the final shipped HTML plus the parsed AST and JS weight for one route.

type Severity

type Severity int

Severity classifies a finding. Off disables a rule entirely.

const (
	// Off disables the rule (or an individual finding is ignored).
	Off Severity = iota
	// Warning reports a problem without failing the build/check by default.
	Warning
	// Error reports a problem that fails the build/check by default.
	Error
)

func ParseSeverity

func ParseSeverity(s string) Severity

ParseSeverity parses "error"/"warning"/"off" (case-insensitive). Unknown values map to Off.

func (Severity) String

func (s Severity) String() string

Jump to

Keyboard shortcuts

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