check

type CheckContext ¶

type CheckContext struct {
	Resource       string
	DocName        string // aliased name used in doc file (empty = same as Resource)
	Type           *config.Type
	Schema         *schema.ResourceSchema
	FunctionSchema *schema.FunctionSchema
	IdentitySchema *schema.IdentitySchema
	Doc            *doc.Document
}

CheckContext carries all inputs a Rule needs to produce findings.

func (c CheckContext) ResourceNames() []string

type ExampleSectionRule ¶ added in v0.3.0

type ExampleSectionRule struct {
	AllowLanguages []string
}

ExampleSectionRule validates the content of the ## Example Usage section. Checks:

• Heading text is "Example Usage"
• All fenced code blocks use an allowed language (default: terraform, hcl)
• All code blocks contain the resource name

func (r *ExampleSectionRule) Check(ctx CheckContext) []Result

func (r *ExampleSectionRule) Name() string

type FileCheckContext ¶

type FileCheckContext struct {
	Resource string
	Type     *config.Type
	Path     string
	Content  []byte
}

FileCheckContext carries all inputs a FileRule needs to produce findings.

type FileCheckRule ¶ added in v0.4.0

type FileCheckRule struct {
	MaxSize                 int64    // bytes; 0 means use default (500000)
	AllowExtensions         []string // e.g. [".md", ".html.markdown"]; empty means no check
	AllowRegistryExtensions []string // stricter set for registry layout; empty means no check
	InlineLinks             *bool    // when true, flag reference-style links
}

FileCheckRule validates file-level properties: size limit, extension, and link style.

func (r *FileCheckRule) CheckFile(ctx FileCheckContext) []Result

func (r *FileCheckRule) Name() string

type FileMatchRule ¶ added in v0.4.0

type FileMatchRule struct {
	RequireDoc    *bool // default true
	RequireSchema *bool // default true
	MixedLayout   *bool // default true

	IgnoreMissing []string // resources that don't need a doc file
	IgnoreExtra   []string // doc files that don't need a schema resource
}

FileMatchRule validates file↔schema alignment:

• require_doc: every schema resource must have a doc file
• require_schema: every doc file must have a matching schema resource
• mixed_layout: can't mix website/docs/ and docs/ layouts

func (r *FileMatchRule) Check(cfg *config.Config, ps *schema.ProviderSchema) []Result

func (r *FileMatchRule) Name() string

type FileRule ¶

type FileRule interface {
	Name() string
	CheckFile(ctx FileCheckContext) []Result
}

FileRule is the interface for checks that operate on the raw bytes of a resource documentation file, independent of the markdown AST. Runner reads each file exactly once per invocation and passes the content to every FileRule alongside the parsed Document that Rules consume.

type FrontmatterRule ¶

type FrontmatterRule struct {
	RequireSubcategory   bool
	RequirePageTitle     bool
	RequireDescription   bool
	RequireLayout        bool
	ForbidSubcategory    bool
	ForbidPageTitle      bool
	ForbidDescription    bool
	ForbidLayout         bool
	ForbidSidebarCurrent bool

	AllowSubcategories []string
	// AllowEmptySubcategoryTargets lists target names for which subcategory: ""
	// is treated as absent (skips the allowlist check). Use for doc types such
	// as functions that legitimately carry no subcategory.
	AllowEmptySubcategoryTargets []string
}

FrontmatterRule validates the YAML frontmatter of a provider documentation file — the block delimited by "---" at the top of each .html.markdown / .md file. It is the successor to tfproviderdocs's FrontMatterCheck; the field coverage and error shapes are chosen to find the same problems.

All require/forbid toggles default to false so the rule is inert until configured. AllowSubcategories, when non-empty, restricts the set of valid subcategory values; an empty slice means "any subcategory is fine".

func (r *FrontmatterRule) CheckFile(ctx FileCheckContext) []Result

func (r *FrontmatterRule) Name() string

type ImportSectionRule ¶

type ImportSectionRule struct {
	RequireIdentitySection bool
}

ImportSectionRule validates the content of the ## Import section. Checks:

• Style: no passive voice ("can be imported"), no "e.g."
• Structure: code blocks present, contain resource name, correct types
• Ordering: terraform blocks before console blocks
• Identity: if resource has identity schema and RequireIdentitySection is true, validates identity import block and ### Identity Schema subsection

func (r *ImportSectionRule) Check(ctx CheckContext) []Result

func (r *ImportSectionRule) Name() string

type RegionArgumentRule ¶ added in v0.4.0

type RegionArgumentRule struct {
	// IgnoreResources lists resources that should not be checked for region.
	IgnoreResources []string
}

RegionArgumentRule validates that region-aware resources document the "region" argument. This is provider-specific (primarily AWS) and only fires for types with RegionAware = true.

func (r *RegionArgumentRule) Check(ctx CheckContext) []Result

func (r *RegionArgumentRule) Name() string

type Result ¶

type Result struct {
	Rule     string   `json:"rule"`
	Resource string   `json:"resource"`
	Path     string   `json:"path,omitempty"`
	Line     int      `json:"line,omitempty"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
	Block    string   `json:"block,omitempty"`
}

Result represents a single finding from a check.

type Rule ¶

type Rule interface {
	Name() string
	Check(ctx CheckContext) []Result
}

Rule is the interface all per-resource checks implement. A Rule compares a resource's schema against its parsed markdown document. For checks that operate on raw file content (YAML frontmatter, file size, line-level scanning, etc.) implement FileRule instead.

type Runner ¶

type Runner struct {
	Schema                    *schema.ProviderSchema
	Config                    *config.Config
	Rules                     []Rule
	FileRules                 []FileRule
	Logger                    *slog.Logger
	HeadingTemplates          doc.HeadingTemplates
	PreferredHeadingTemplates doc.HeadingTemplates
}

Runner orchestrates checks across every target the provider exposes.

Targets are discovered by iterating the configured types (config.Config.Types) and asking the loaded schema for the names of each type's kind. For each target, Runner resolves the doc file from the type's website_paths templates, reads and parses it once, and invokes every Rule (schema + AST) and every FileRule (raw bytes) against it.

The Runner no longer hard-codes "resource" vs "data source" — everything it does is driven by config.Type definitions. Adding a new Terraform category means adding a type block (and, if block-based, registering a schema accessor); the Runner requires no changes.

func (r *Runner) RunAll() []Result

func (r *Runner) RunOne(name, kind string) ([]Result, error)

func (r *Runner) RunPrefix(prefix, kind string) []Result

type SchemaDocsRule ¶ added in v0.3.0

type SchemaDocsRule struct {
	// Coverage options
	IgnoreDeprecated   bool
	ImplicitAttributes []string
	AllowPhantoms      []string
	SkipBlocks         []string

	// AllowInlineReadOnly permits Read-Only (computed-only) attributes to
	// be documented inline in Argument Reference with a "(Read-Only)" label,
	// alongside Required and Optional siblings, instead of requiring them
	// in Attribute Reference. Default false: strict separation — Argument
	// Reference is for configurable attributes only.
	AllowInlineReadOnly *bool

	// Sub-check toggles (nil = enabled)
	Coverage    *bool
	Ordering    *bool
	Description *bool
	Heading     *bool
	Format      *bool
	Labels      *bool
	Byline      *bool
	Deprecated  *bool

	// Description options
	BadPrefixes []string

	// Heading options
	Preferred doc.HeadingTemplates

	// Format sub-options (nil = enabled)
	NoCodeBlocks              *bool
	SingleLineAttrs           *bool
	UninterruptedLists        *bool
	AllowAttributeIndentation *bool // nil/true = allow indented sub-attrs in Attribute Reference
}

SchemaDocsRule validates argument and attribute sections against the schema. Sub-checks (all enabled by default, disable with pointer-to-false):

• Coverage: every schema attr documented, every documented attr in schema
• Ordering: alphabetical within required/optional/unmarked groups
• Description: descriptions don't start with bad prefixes
• Heading: block headings match preferred style
• Format: no code blocks, single-line attrs, uninterrupted lists
• Labels: arguments have (Required)/(Optional), attributes do not

func (r *SchemaDocsRule) Check(ctx CheckContext) []Result

func (r *SchemaDocsRule) Name() string

type SectionPresenceRule ¶

type SectionPresenceRule struct {
	EnforceOrder         *bool
	AllowUnknownSections *bool
}

SectionPresenceRule enforces the structural integrity of a documentation file: required sections are present, forbidden sections are absent, sections appear in the order declared on the Type, and no stray level-2 headings occur outside the recognized set.

Configuration sources:

• Type.Sections — declares which sections this type may contain, in what order, with required and forbidden flags. The order of section blocks IS the canonical order. A Type with no Sections is treated as "no structural rules" and skipped. Section names may be canonical (title, signature, example, arguments, attributes, timeouts, import) or custom (any lowercase snake_case identifier the type opts into, e.g. "usage_notes", "dependency_management").
• CheckConfig.EnforceOrder — when nil or true, out-of-order sections are reported. Set to false to skip order enforcement.
• CheckConfig.AllowUnknownSections — when nil or false, level-2 headings that do not match a recognized section are reported. Set to true to permit them silently (e.g. for free-form provider docs).

Special handling: Timeouts is also driven by the schema when one is available — the schema's timeouts block, not the Type, decides whether the section is required.

func (r *SectionPresenceRule) Check(ctx CheckContext) []Result

func (r *SectionPresenceRule) Name() string

type Severity ¶

type Severity int

Severity indicates the severity of a check result.

const (
	SeverityError Severity = iota
	SeverityWarning
)

func (s Severity) String() string

type SignatureSectionRule ¶ added in v0.3.0

type SignatureSectionRule struct{}

SignatureSectionRule validates the content of the ## Signature section. Checks:

• At least one code block is present
• Code block contains the function name
• Code block contains all parameter names from the schema

func (r *SignatureSectionRule) Check(ctx CheckContext) []Result

func (r *SignatureSectionRule) Name() string

type TimeoutsSectionRule ¶

type TimeoutsSectionRule struct{}

TimeoutsSectionRule validates that the documented timeout actions match the schema. It checks:

• Every schema timeout action is documented
• Every documented timeout action exists in the schema

No config fields — entirely schema-driven. Path scoping (prefixes, targets) is handled by the Runner's AppliesTo mechanism.

func (r *TimeoutsSectionRule) Check(ctx CheckContext) []Result

func (r *TimeoutsSectionRule) Name() string

type TitleSectionRule ¶

type TitleSectionRule struct {
	// AllowPrefixes overrides DefaultTitleSectionPrefixes. Empty uses the
	// default.
	AllowPrefixes []string
}

TitleSectionRule validates the first-level heading of a provider doc page:

• a title is present,
• its heading level is 1,
• its text begins with one of the allow-listed prefixes followed by ": ",
• no fenced code blocks appear before the first level-2 heading (example code belongs under ## Example Usage).

This is the successor to tfproviderdocs's checkTitleSection. Error messages are chosen to look familiar to anyone migrating from the older tool so the signal a provider acts on is unchanged.

func (r *TitleSectionRule) Check(ctx CheckContext) []Result

func (r *TitleSectionRule) Name() string