Documentation
¶
Overview ¶
Package config loads and validates the per-project .awf/ configuration: a skeleton config.yaml plus per-target sidecar YAMLs and convention parts.
Index ¶
- Constants
- func AppendLocalDoc(src []byte, doc LocalDoc) ([]byte, error)
- func ConfigPath(root string) string
- func IsSingletonKind(kind string) bool
- func LockPath(root string) string
- func MarshalSkeleton(s Skeleton) ([]byte, error)
- func RootDir(root string) string
- func SetArrayMember(src []byte, key, name string, add bool) ([]byte, error)
- func ValidateArtifactName(kind, name string) error
- func ValidateDomainName(name string) error
- func ValidatePathGlobs(globs []string) error
- type AuditConfig
- type BootstrapConfig
- type CommitPolicyConfig
- type CommitPolicyIdentity
- type CommitPolicySigner
- type Config
- func (c *Config) HasSidecar(kind, name string) (bool, error)
- func (c *Config) NormalizedLocalDocs() []LocalDoc
- func (c *Config) OperationTree() OperationTree
- func (c *Config) PartPath(kind, artifact, section string) string
- func (c *Config) ReadPart(kind, artifact, section string) ([]byte, bool, error)
- func (c *Config) ReadPartPath(full string) ([]byte, error)
- func (c *Config) ReadSidecar(rel string) ([]byte, bool)
- func (c *Config) Sidecar(kind, name string) (Sidecar, error)
- func (c *Config) Source() []byte
- func (c *Config) Validate() error
- type CurrentStateConfig
- type CurrentStateSource
- type Facts
- type LocalDoc
- type LocalDocs
- type MemoryCiteConfig
- type MemoryExemption
- type OperationTree
- type ProseExemption
- type ProseGateConfig
- type RenderConfig
- type ScopeSpec
- type SectionOverride
- type Sidecar
- type Skeleton
- type SkeletonAudit
- type TreeReader
Constants ¶
const DirName = ".awf"
DirName is the config-tree directory name at the project root.
const DocsDir = "docs"
DocsDir is the fixed root for awf-managed documentation.
Variables ¶
This section is empty.
Functions ¶
func AppendLocalDoc ¶ added in v0.36.0
AppendLocalDoc appends one strict local-document declaration without changing unrelated config structure. It refuses malformed existing declarations and duplicates.
func ConfigPath ¶ added in v0.6.0
ConfigPath returns the skeleton config.yaml path for a project root.
func IsSingletonKind ¶
IsSingletonKind reports whether kind is an always-on singleton whose sidecar lives at <root>/<kind>.yaml and whose parts live under <root>/parts/<kind>/ (ADR-0021, ADR-0043).
func MarshalSkeleton ¶
MarshalSkeleton renders a fresh config.yaml from s in the canonical awf format (two-space block style). It is the construction half of internal/config's ownership of config.yaml serialization (ADR-0026).
func RootDir ¶ added in v0.6.0
RootDir returns the config-tree directory for a project root (<root>/.awf).
func SetArrayMember ¶
SetArrayMember adds or removes name in the sequence under key in a config.yaml source, via a yaml.Node round-trip that preserves comments and every untouched key (ADR-0026). The edited sequence is normalized to block style, so a flow-style input (`key: [a, b]`) is accepted. Adding a member already present is a no-op; removing a member absent from the key (or a key absent on remove) errors. touches-state: config/configuration:config-mutation-roundtrip - yaml.Node add/remove round-trip; proof in edit_test.go
func ValidateArtifactName ¶ added in v0.10.0
ValidateArtifactName reports whether a flat artifact name uses the catalog's lowercase kebab-case grammar. The charset is frontmatter-safe: it excludes path separators, awf's reserved "_" namespace, and punctuation that would break a generated skill's YAML frontmatter. Migration also uses it to recognize the historical flat skill and agent sidecar surface.
func ValidateDomainName ¶
ValidateDomainName reports whether name is a usable domain key: non-empty and free of path separators or "..".
func ValidatePathGlobs ¶ added in v0.33.0
ValidatePathGlobs rejects empty, duplicate, or malformed anchored path globs.
Types ¶
type AuditConfig ¶
type AuditConfig struct {
AllowedScopes []ScopeSpec `yaml:"allowedScopes"`
}
AuditConfig carries the repository-specific Conventional Commits scope vocabulary for `awf audit` (ADR-0017). Every audit rule and threshold is fixed in internal/audit; a nil *AuditConfig or an empty AllowedScopes accepts any scope.
type BootstrapConfig ¶ added in v0.5.0
type BootstrapConfig struct {
Enabled bool `yaml:"enabled"`
}
BootstrapConfig configures the rendered .awf/bootstrap.sh singleton (ADR-0040, relocated by ADR-0047). A nil *BootstrapConfig (key absent) and Enabled false both mean "do not render"; only Enabled true renders the artifact - a nested enable entry rather than a top-level scalar bool (the Alternatives table rejected the bare bool).
type CommitPolicyConfig ¶ added in v0.30.0
type CommitPolicyConfig struct {
GrandfatheredThrough string `yaml:"grandfatheredThrough"`
AllowedIdentities []CommitPolicyIdentity `yaml:"allowedIdentities"`
RequireSignedCommits bool `yaml:"requireSignedCommits"`
AllowedSigners []CommitPolicySigner `yaml:"allowedSigners"`
// contains filtered or unexported fields
}
CommitPolicyConfig is an optional exact-commit provenance policy. Repository resolution and verification belong to later operation owners; this package validates only the authored structural contract.
func (*CommitPolicyConfig) UnmarshalYAML ¶ added in v0.30.0
func (c *CommitPolicyConfig) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML retains optional-list presence while preserving strict nested field validation for the commitPolicy mapping and its records.
type CommitPolicyIdentity ¶ added in v0.30.0
CommitPolicyIdentity is one exact author/committer name and email pair.
type CommitPolicySigner ¶ added in v0.30.0
CommitPolicySigner is one SSH signing principal and public key pair.
type Config ¶
type Config struct {
Prefix string `yaml:"prefix"`
Profile catalog.Profile `yaml:"profile"`
// IntegrationBranch names the branch effort work integrates into. It is
// required-explicit and carries no in-code default (the Prefix precedent,
// not the DocsDir one): the schema migration writes `integrationBranch:
// main` visibly so no adopter silently inherits a branch name it never
// chose (ADR-0202 Decision 6, keeping ADR-0127's silent-default removal).
IntegrationBranch string `yaml:"integrationBranch"`
Vars map[string]any `yaml:"vars"`
Domains []string `yaml:"domains"`
Tags map[string]string `yaml:"tags"`
ContextIgnore []string `yaml:"contextIgnore"`
CurrentState *CurrentStateConfig `yaml:"currentState"`
Audit *AuditConfig `yaml:"audit"`
Bootstrap *BootstrapConfig `yaml:"bootstrap"`
ProseGate *ProseGateConfig `yaml:"proseGate"`
MemoryCite *MemoryCiteConfig `yaml:"memoryCite"`
CommitPolicy *CommitPolicyConfig `yaml:"commitPolicy"`
Render *RenderConfig `yaml:"render"`
LocalDocs LocalDocs `yaml:"localDocs"`
// contains filtered or unexported fields
}
Config is the skeleton config.yaml: repository facts and render shaping.
func Load ¶
Load reads <awfDir>/config.yaml with the strict decoder and records awfDir as the sidecar/part resolution root.
func Parse ¶ added in v0.18.0
Parse strictly decodes config.yaml bytes, records awfDir as the sidecar/part resolution root, and applies defaults.
func ParseTree ¶ added in v0.22.0
func ParseTree(awfDir string, b []byte, read TreeReader) (*Config, error)
ParseTree decodes config bytes and injects the selected config-tree reader.
func (*Config) HasSidecar ¶ added in v0.10.0
HasSidecar reports whether a declaring sidecar file exists for an artifact - the presence signal that marks a non-catalog name as an intentional local artifact rather than a typo (ADR-0068).
func (*Config) NormalizedLocalDocs ¶ added in v0.36.0
NormalizedLocalDocs returns the deterministic projection without rewriting authored YAML list order.
func (*Config) OperationTree ¶ added in v0.40.0
func (c *Config) OperationTree() OperationTree
OperationTree returns the selected tree binding without making it part of Facts. Filesystem loading and snapshot parsing retain their existing policy.
func (*Config) ReadPart ¶ added in v0.22.0
ReadPart returns selected-universe convention-part bytes.
func (*Config) ReadPartPath ¶ added in v0.22.0
ReadPartPath reads a consumed absolute part path through the selected reader.
func (*Config) ReadSidecar ¶ added in v0.22.0
ReadSidecar returns selected-universe sidecar bytes by config-relative path.
func (*Config) Sidecar ¶
Sidecar reads <root>/<kind>/<name>.yaml; agents-doc lives at <root>/agents-doc.yaml. A missing file yields a zero Sidecar (publication-safe: empty data/sections).
type CurrentStateConfig ¶ added in v0.18.0
type CurrentStateConfig struct {
Sources []CurrentStateSource `yaml:"sources"`
TestGlobs []string `yaml:"testGlobs"`
}
CurrentStateConfig configures canonical current-state topic validation. Sources define claim-bearing scan inputs; TestGlobs define proof-source boundaries.
func (*CurrentStateConfig) UnmarshalYAML ¶ added in v0.18.0
func (c *CurrentStateConfig) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML preserves strict nested field validation for the custom-decoded current-state mapping.
type CurrentStateSource ¶ added in v0.18.0
type CurrentStateSource struct {
Globs []string `yaml:"globs"`
Marker string `yaml:"marker"`
Close string `yaml:"close"`
// contains filtered or unexported fields
}
CurrentStateSource describes one marker-bearing source family. closeSet distinguishes an omitted close token from an explicitly empty one.
func (*CurrentStateSource) UnmarshalYAML ¶ added in v0.18.0
func (s *CurrentStateSource) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML retains close-token presence while preserving strict nested field validation for the custom-decoded source mapping.
type Facts ¶ added in v0.40.0
type Facts struct {
// contains filtered or unexported fields
}
Facts is the immutable, configuration-owned snapshot consumed outside this package. It deliberately excludes parsing and filesystem state; callers get a fresh deep copy for each observation.
type LocalDoc ¶ added in v0.36.0
type LocalDoc struct {
Name string `yaml:"name"`
Title string `yaml:"title"`
Description string `yaml:"description"`
}
LocalDoc declares one project-owned document beneath docs. Its custom decoder keeps the record closed even when YAML's permissive mapping decoder changes.
type LocalDocs ¶ added in v0.36.0
type LocalDocs []LocalDoc
LocalDocs preserves the distinction between an omitted declaration list and an explicitly null or non-list value.
type MemoryCiteConfig ¶ added in v0.30.0
type MemoryCiteConfig struct {
Exemptions []MemoryExemption `yaml:"exemptions"`
}
MemoryCiteConfig configures exemptions for `awf check repo memory` (ADR-0158), which always scans the staged decision-record directories and every cleaned commit-message body for a citation of a specific working-memory file. A nil *MemoryCiteConfig means no paths are exempt.
type MemoryExemption ¶ added in v0.30.0
MemoryExemption permits citations in one path. A nil Count permits any number of them; a non-nil Count pins the expected number, so an added citation in an exempt file still fails.
type OperationTree ¶ added in v0.40.0
type OperationTree struct {
// contains filtered or unexported fields
}
OperationTree binds one selected config-tree representation for operations that read sidecars and convention parts. It is concrete by design: TreeReader remains the existing parsing contract rather than a new provider seam.
func (OperationTree) Bind ¶ added in v0.40.0
func (t OperationTree) Bind(f Facts) *Config
Bind combines immutable facts with this operation's selected tree. This is the only translation back to Config for existing tree-reading operations.
type ProseExemption ¶ added in v0.18.0
type ProseExemption struct {
Path string `yaml:"path"`
Codepoint string `yaml:"codepoint"`
Count *int `yaml:"count"`
}
ProseExemption exempts one guarded codepoint in one path. Codepoint is spelled "U+2014", never the character itself. A nil Count permits any number of occurrences; a non-nil Count pins the expected number, so an added occurrence in an exempt file still fails. Former ellipsis and curly-quote exemptions remain accepted as inert compatibility input.
type ProseGateConfig ¶ added in v0.18.0
type ProseGateConfig struct {
Exemptions []ProseExemption `yaml:"exemptions"`
}
ProseGateConfig configures exemptions for `awf check repo prose`, which always scans every tracked text file for punctuation-restraint violations. A nil *ProseGateConfig means no paths or guarded codepoints are exempt.
type RenderConfig ¶ added in v0.34.0
type RenderConfig struct {
TemplateSourceRoot string `yaml:"templateSourceRoot"`
}
RenderConfig holds optional rendering facts.
type ScopeSpec ¶ added in v0.8.0
ScopeSpec is one allowed commit scope: a name and an optional human meaning. In config a scope is written either as a bare string (name only) or a {name, meaning} mapping (ADR-0056).
func AuditScopes ¶ added in v0.32.0
func AuditScopes(a *AuditConfig) []ScopeSpec
AuditScopes returns the configured scope vocabulary, if the audit block exists.
type SectionOverride ¶
type SectionOverride struct {
Drop bool `yaml:"drop"`
}
SectionOverride is a sidecar's per-section override. Body replacement is by convention part only; the field set is deliberately just Drop. touches-state: config/configuration:no-replacewith - SectionOverride field set omits replaceWith; proof in config_test.go
type Sidecar ¶
type Sidecar struct {
Data map[string]any `yaml:"data"`
DataDefaults map[string]bool `yaml:"dataDefaults"`
Sections map[string]SectionOverride `yaml:"sections"`
// Paths declares a domain's file territory as anchored path globs
// (ADR-0077); read only from domain sidecars, inert on other kinds.
Paths []string `yaml:"paths"`
}
Sidecar holds a single target's non-prose configuration: structured render data and per-section overrides. It lives at <awfDir>/<kind>/<name>.yaml (agents-doc: <awfDir>/agents-doc.yaml). An absent sidecar is the zero Sidecar (publication-safe: empty data/sections).
type Skeleton ¶
type Skeleton struct {
Prefix string `yaml:"prefix"`
Profile catalog.Profile `yaml:"profile"`
// IntegrationBranch is written explicitly because the key is required and
// carries no in-code default (ADR-0202 Decision 6): a scaffold omitting it
// would emit a config that fails its own validation on the next open.
IntegrationBranch string `yaml:"integrationBranch"`
Vars map[string]string `yaml:"vars"`
Audit *SkeletonAudit `yaml:"audit,omitempty"`
Bootstrap *BootstrapConfig `yaml:"bootstrap,omitempty"`
}
Skeleton is the input to MarshalSkeleton: the fields a freshly-scaffolded .awf/config.yaml carries. Vars is typed map[string]string (not map[string]any) so a nil/null var value is unrepresentable - the scaffold seeds each var with an empty string, which marshals as `x: ""`. A nil interface would marshal as `x: null` and decode back to a nil value that renders as "<no value>", tripping the publication-safe check (ADR-0026 Decision 3).
type SkeletonAudit ¶ added in v0.6.0
type SkeletonAudit struct {
AllowedScopes []string `yaml:"allowedScopes"`
}
SkeletonAudit is the audit block a scaffold can seed (ADR-0051): only allowedScopes - the one audit field init collects. Deliberately not *AuditConfig, whose zero-value fields would serialize as explicit settings.