config

Documentation

Index

• Constants
• type CheckConfig
  • func (c CheckConfig) AppliesTo(name, typeName string) bool
• type Config
  • func Load(path string) (*Config, error)
  • func (c *Config) CheckBool(checkName, field string, defaultVal bool) bool
  • func (c *Config) FileMatchIgnoreMissing() []string
  • func (c *Config) GetCheck(name string) CheckConfig
  • func (c *Config) GetType(name string) *Type
  • func (c *Config) IsCheckEnabled(name string) bool
  • func (c *Config) ProviderName() string
  • func (c *Config) ShouldIgnoreContents(resource, typeName string) bool
  • func (c *Config) TypeNames() []string
• type SectionRequirement
  • func (s SectionRequirement) IsValid() bool
• type Type
  • func (t *Type) ResolveDocPath(target, providerPrefix string) []string
  • func (t *Type) Validate() error

Constants

const DefaultConfigFile = ".swissshepherd.hcl"

Types

type CheckConfig

type CheckConfig struct {
	Name    string `hcl:"name,label"`
	Enabled bool   `hcl:"enabled,optional"`

	// BlockHeadingStyles defines templates for recognizing block headings.
	// Use {Block} as placeholder for the block name (snake_case).
	// Use {Title} as placeholder for title-case name (converted to snake_case).
	// Default: ["`{Block}` Block", "{Block} Block", "`{Block}`", "{Block}", "{Title}"]
	BlockHeadingStyles []string `hcl:"block_heading_styles,optional"`

	// PreferBlockHeadingStyles defines the target heading format(s).
	// When a block heading matches an accepted style but not a preferred style,
	// a warning is emitted suggesting the preferred format.
	PreferBlockHeadingStyles []string `hcl:"prefer_block_heading_styles,optional"`

	// Path scoping — control which targets this check applies to.
	// Empty lists mean "all". When multiple allowlists are set, a target
	// must satisfy each populated axis:
	//
	//   - Types: include only targets whose type name is in this list.
	//   - Prefixes / Targets: a target's name must have one of the listed
	//     prefixes OR be listed exactly in Targets. (The two name-axis
	//     lists are OR'd together; they're two ways of saying "include
	//     these names".)
	//
	// IgnoreTargets subtracts unconditionally: a name in IgnoreTargets is
	// never checked even when allowlists include it. IgnoreTargetsFile is
	// the file form of the same list (one name per line; '#' starts a
	// comment; relative paths resolve against CWD like every other _file
	// option).
	Types             []string `hcl:"types,optional"`
	Prefixes          []string `hcl:"prefixes,optional"`
	Targets           []string `hcl:"targets,optional"`
	IgnoreTargets     []string `hcl:"ignore_targets,optional"`
	IgnoreTargetsFile string   `hcl:"ignore_targets_file,optional"`
	IgnorePrefixes    []string `hcl:"ignore_prefixes,optional"`

	// Frontmatter rule options. Set require_* to fail when a field is absent;
	// set forbid_* to fail when it is present. A field covered by both require
	// and forbid is a configuration error — require wins but emits both.
	RequireSubcategory   bool `hcl:"require_subcategory,optional"`
	RequirePageTitle     bool `hcl:"require_page_title,optional"`
	RequireDescription   bool `hcl:"require_description,optional"`
	RequireLayout        bool `hcl:"require_layout,optional"`
	ForbidSubcategory    bool `hcl:"forbid_subcategory,optional"`
	ForbidPageTitle      bool `hcl:"forbid_page_title,optional"`
	ForbidDescription    bool `hcl:"forbid_description,optional"`
	ForbidLayout         bool `hcl:"forbid_layout,optional"`
	ForbidSidebarCurrent bool `hcl:"forbid_sidebar_current,optional"`

	// Subcategory allowlist for the frontmatter rule. When non-empty, a
	// frontmatter subcategory value outside this list is reported. The allowlist
	// only fires when subcategory is actually present in the file — pair with
	// require_subcategory if absence should also fail.
	AllowSubcategories           []string `hcl:"allow_subcategories,optional"`
	AllowSubcategoriesFile       string   `hcl:"allow_subcategories_file,optional"`
	AllowEmptySubcategoryTargets []string `hcl:"allow_empty_subcategory_targets,optional"`

	// TitleSection rule options.
	//
	// AllowPrefixes replaces the default set of permitted level-1 heading
	// prefixes ("Action", "Data Source", "Ephemeral", "Function",
	// "List Resource", "Resource"). Leave empty to use the default.
	AllowPrefixes []string `hcl:"allow_prefixes,optional"`

	// Completeness rule options.
	IgnoreDeprecated   *bool    `hcl:"ignore_deprecated,optional"`
	ImplicitAttributes []string `hcl:"implicit_attributes,optional"`
	AllowPhantoms      []string `hcl:"allow_phantoms,optional"`
	SkipBlocks         []string `hcl:"skip_blocks,optional"`

	// DescriptionStyle rule options.
	BadPrefixes []string `hcl:"bad_prefixes,optional"`

	// FormatStyle rule options. nil means enabled (default true).
	NoCodeBlocks       *bool `hcl:"no_code_blocks,optional"`
	SingleLineAttrs    *bool `hcl:"single_line_attrs,optional"`
	UninterruptedLists *bool `hcl:"uninterrupted_lists,optional"`

	// SchemaDocsRule sub-check toggles. nil means enabled (default true).
	Coverage    *bool `hcl:"coverage,optional"`
	Ordering    *bool `hcl:"ordering,optional"`
	Description *bool `hcl:"description,optional"`
	Heading     *bool `hcl:"heading,optional"`
	Format      *bool `hcl:"format,optional"`
	Labels      *bool `hcl:"labels,optional"`
	Byline      *bool `hcl:"byline,optional"`

	// ImportSection rule options.
	RequireIdentitySection *bool `hcl:"require_identity_section,optional"`

	// ExampleSection rule options.
	AllowLanguages []string `hcl:"allow_languages,optional"`

	// FileCheck rule options.
	MaxFileSize             int64    `hcl:"max_file_size,optional"`
	AllowExtensions         []string `hcl:"allow_extensions,optional"`
	AllowRegistryExtensions []string `hcl:"allow_registry_extensions,optional"`

	// DirectoryLayout rule options.
	IgnoreCdktf bool `hcl:"ignore_cdktf,optional"`

	// FileMatch rule options.
	RequireDoc        *bool    `hcl:"require_doc,optional"`
	RequireSchema     *bool    `hcl:"require_schema,optional"`
	MixedLayout       *bool    `hcl:"mixed_layout,optional"`
	IgnoreMissing     []string `hcl:"ignore_missing,optional"`
	IgnoreMissingFile string   `hcl:"ignore_missing_file,optional"`
	IgnoreExtra       []string `hcl:"ignore_extra,optional"`
	IgnoreExtraFile   string   `hcl:"ignore_extra_file,optional"`

	// RegionArgument rule options.
	IgnoreResources     []string `hcl:"ignore_resources,optional"`
	IgnoreResourcesFile string   `hcl:"ignore_resources_file,optional"`
}

CheckConfig represents a single check block in the config.

func (CheckConfig) AppliesTo

func (c CheckConfig) AppliesTo(name, typeName string) bool

AppliesTo reports whether this check's path-scoping admits the given (name, typeName) target.

Semantics:

1. IgnoreTargets wins unconditionally — a listed name is always excluded.
2. When Types is non-empty, typeName must be in it.
3. When either Prefixes or Targets is non-empty, the name must satisfy at least one: name has a listed prefix, OR name equals a listed exact target. Both lists empty means "any name is fine".

Intended usage: the Runner calls AppliesTo per-rule before invoking it, so each check can roll out independently across a large provider (the service-by-service migration the phase-3 design was built for).

type Config

type Config struct {
	ProviderSource string `hcl:"provider_source,optional"`
	ProviderDir    string `hcl:"provider_dir,optional"`
	SchemaJSON     string `hcl:"schema_json,optional"`

	// IgnoreContentsCheck suppresses all schema+doc rule findings for the
	// listed target names. Useful for deprecated/removed resources whose docs
	// are intentionally minimal stubs.
	IgnoreContentsCheck     []string `hcl:"ignore_contents_check,optional"`
	IgnoreContentsCheckFile string   `hcl:"ignore_contents_check_file,optional"`

	// FileAliases maps a schema target name to the doc target name used for
	// path resolution. Keys can be plain names (apply to all types) or
	// type-qualified as "type/name" (e.g. "list_resource/aws_ebs_volume").
	FileAliases map[string]string `hcl:"file_aliases,optional"`

	// Types defines every documentation category swissshepherd knows about.
	// A set of standard types (resource, data_source, ephemeral, function,
	// list_resource, action, guide, index) ships embedded; user blocks with
	// the same name replace defaults wholesale, new names add new types.
	Types []Type `hcl:"type,block"`

	Checks []CheckConfig `hcl:"check,block"`
}

Config is the top-level configuration for swissshepherd.

func Load

func Load(path string) (*Config, error)

Load reads and parses an HCL config file. Returns a zero-value Config if the file doesn't exist (with default types already merged in).

Relative paths in the config (provider_dir, docs_path, schema_json, and any *_file option) are interpreted by the OS relative to the current working directory at the time swissshepherd runs — the same convention as terraform, docker, go, make, and other tools. The location of the config file itself does not anchor paths; run swissshepherd from the provider repo root (or wherever your paths are written relative to) and point --config at the config file.

func (*Config) CheckBool

func (c *Config) CheckBool(checkName, field string, defaultVal bool) bool

CheckBool returns a named bool option from a check block, or the given default when the check block doesn't exist or the field is nil.

func (*Config) FileMatchIgnoreMissing

func (c *Config) FileMatchIgnoreMissing() []string

FileMatchIgnoreMissing returns the ignore_missing list from the file_match check block. Used by the Runner to suppress "doc not found" log warnings.

func (*Config) GetCheck

func (c *Config) GetCheck(name string) CheckConfig

GetCheck returns the CheckConfig for a named check, or a disabled default.

func (*Config) GetType

func (c *Config) GetType(name string) *Type

GetType returns the Type with the given name, or nil when no such Type is defined. The lookup is linear — the slice is small (a handful of entries in practice), and linear keeps the return ordering stable.

func (*Config) IsCheckEnabled

func (c *Config) IsCheckEnabled(name string) bool

IsCheckEnabled returns true if a check is enabled. Checks are enabled by default unless explicitly disabled in config.

func (*Config) ProviderName

func (c *Config) ProviderName() string

ProviderName extracts the short provider name from the source.

func (*Config) ShouldIgnoreContents

func (c *Config) ShouldIgnoreContents(resource, typeName string) bool

ShouldIgnoreContents reports whether schema+doc rules should be skipped for the given resource name (deprecated stubs, etc.). Entries can be bare names ("aws_kms_secret") matching any type, or type-qualified ("data_source/aws_kms_secret").

func (*Config) TypeNames

func (c *Config) TypeNames() []string

TypeNames returns the names of all loaded types, in config order.

type SectionRequirement

type SectionRequirement string

SectionRequirement captures the tri-state required/optional/forbidden requirement for a documentation section. Stored as a string so it decodes cleanly from HCL; validated at config load.

const (
	SectionOptional  SectionRequirement = "optional"
	SectionRequired  SectionRequirement = "required"
	SectionForbidden SectionRequirement = "forbidden"
)

Known SectionRequirement values. Any other value is a config error.

func (SectionRequirement) IsValid

func (s SectionRequirement) IsValid() bool

IsValid reports whether the value is one of the three accepted requirement strings.

type Type

type Type struct {
	Name string `hcl:"name,label"`

	// SchemaKind ties this Type to a schema-accessor registered in
	// internal/schema. The built-in accessors are: "resource", "data_source",
	// "ephemeral", "function", "list_resource", "action", and "none" (for
	// content-only categories like guides and the index).
	SchemaKind string `hcl:"schema_kind"`

	// WebsitePaths is a list of templates for resolving a target's doc file.
	// Each template uses "{name}" as the placeholder for the
	// provider-prefix-stripped target name (e.g., "instance" for
	// "aws_instance"). Templates are tried in order; the first existing file
	// wins. Supporting multiple templates lets a single type handle both
	// registry ("docs/resources/{name}.md") and legacy
	// ("website/docs/r/{name}.html.markdown") layouts simultaneously.
	WebsitePaths []string `hcl:"website_paths"`

	// TitlePrefix is the allowed "<Kind>: " prefix for the level-1 heading of
	// this type's doc. Empty means no title constraint (used for guides).
	TitlePrefix string `hcl:"title_prefix,optional"`

	// ArgumentsBylines is the set of paragraph texts allowed immediately
	// under "## Argument Reference". Empty means no byline constraint.
	ArgumentsBylines []string `hcl:"arguments_bylines,optional"`

	// AttributesBylines is the analogous set for "## Attribute Reference".
	AttributesBylines []string `hcl:"attributes_bylines,optional"`

	// ArgumentsHeading overrides the expected "## Argument Reference" text.
	// Functions use "Arguments" instead, for example.
	ArgumentsHeading string `hcl:"arguments_heading,optional"`

	// AllowMissingArgumentsByline relaxes the byline requirement — useful
	// for categories where the section header alone is enough.
	AllowMissingArgumentsByline bool `hcl:"allow_missing_arguments_byline,optional"`

	// Section requirements: "required", "optional", or "forbidden". Empty
	// string means "optional" (the safe default).
	RequireAttributes SectionRequirement `hcl:"require_attributes,optional"`
	RequireImport     SectionRequirement `hcl:"require_import,optional"`
	RequireTimeouts   SectionRequirement `hcl:"require_timeouts,optional"`
	RequireSignature  SectionRequirement `hcl:"require_signature,optional"`

	// Frontmatter field requirements. FrontmatterRequire fields must be
	// present; FrontmatterForbid fields must be absent. The overlap is a
	// config error.
	FrontmatterRequire []string `hcl:"frontmatter_require,optional"`
	FrontmatterForbid  []string `hcl:"frontmatter_forbid,optional"`

	// RegionAware declares whether the enhanced-region argument check
	// applies to this type. Functions, actions, and guides are typically
	// not region-aware.
	RegionAware bool `hcl:"region_aware,optional"`
}

Type describes one category of provider documentation — resource, data source, ephemeral, function, list resource, action, guide, index, or a provider-specific extension.

The Type block in HCL captures everything swissshepherd needs to know about a category *except* the check logic itself: where docs live on disk, where the category's schema lives in the provider schema JSON, and what conventions rules should apply. Defaults for the Terraform-standard categories are embedded; users can add new types or override defaults by name.

func (*Type) ResolveDocPath

func (t *Type) ResolveDocPath(target, providerPrefix string) []string

ResolveDocPath expands a type's website_paths templates for the given target name, returning every candidate path in order. Callers typically try each until one exists. `providerPrefix` is stripped from `target` so "aws_instance" with providerPrefix "aws" yields the candidates for "instance".

func (*Type) Validate

func (t *Type) Validate() error

Validate enforces the non-HCL constraints on a single Type: schema_kind must be non-empty, at least one website_path must be set, section requirements must use one of the allowed strings, and FrontmatterRequire and FrontmatterForbid must not list the same field.