config

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"`
	AllowInlineReadOnly *bool    `hcl:"allow_inline_read_only,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"`
	AllowAttributeIndentation *bool `hcl:"allow_attribute_indentation,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"`
	Deprecated  *bool `hcl:"deprecated,optional"`

	// SectionPresence rule options.
	// EnforceOrder requires sections to appear in the order declared on
	// the Type's section blocks. nil → enabled (strict by default).
	// AllowUnknownSections permits level-2 headings that are not in the
	// Type's section spec; otherwise each is reported as an error.
	// nil → disallowed (strict by default).
	EnforceOrder         *bool `hcl:"enforce_order,optional"`
	AllowUnknownSections *bool `hcl:"allow_unknown_sections,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"`
	InlineLinks             *bool    `hcl:"inline_links,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"`
}

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"`
}

type SectionName string

type SectionSpec struct {
	Name      string `hcl:"name,label"`
	Required  bool   `hcl:"required,optional"`
	Forbidden bool   `hcl:"forbidden,optional"`
}

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"`

	// Sections declares the canonical doc structure for this type. The order
	// of section blocks here IS the expected order in the doc file. Each
	// section block accepts:
	//   - required = true   → section must be present
	//   - forbidden = true  → section must be absent
	//   - both unset        → section is optional (allowed, not required)
	//   - both set          → config error
	//
	// section_presence reads this to enforce presence and (when its
	// enforce_order option is true) order.
	Sections []SectionSpec `hcl:"section,block"`

	// 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"`
}