config

package
v0.44.0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

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

View Source
const DirName = ".awf"

DirName is the config-tree directory name at the project root.

View Source
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

func AppendLocalDoc(src []byte, doc LocalDoc) ([]byte, error)

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

func ConfigPath(root string) string

ConfigPath returns the skeleton config.yaml path for a project root.

func DecodeJSONValue added in v0.44.0

func DecodeJSONValue(s string) (any, error)

DecodeJSONValue decodes exactly one JSON value. JSON's decoder rejects trailing documents.

func EditSidecar added in v0.44.0

func EditSidecar(src []byte, edit SidecarEdit) ([]byte, bool, bool, error)

EditSidecar applies a leaf mutation without rebuilding unrelated YAML nodes. It returns source bytes, whether the sidecar remains present, and whether bytes changed.

func IsSingletonKind

func IsSingletonKind(kind string) bool

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 LockPath added in v0.6.0

func LockPath(root string) string

LockPath returns the awf.lock path for a project root.

func MarshalSkeleton

func MarshalSkeleton(s Skeleton) ([]byte, error)

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

func RootDir(root string) string

RootDir returns the config-tree directory for a project root (<root>/.awf).

func SetArrayMember

func SetArrayMember(src []byte, key, name string, add bool) ([]byte, error)

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.

func ValidateArtifactName added in v0.10.0

func ValidateArtifactName(kind, name string) error

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

func ValidateDomainName(name string) error

ValidateDomainName reports whether name is a usable domain key: non-empty and free of path separators or "..".

func ValidatePathGlobs added in v0.33.0

func ValidatePathGlobs(globs []string) error

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

type CommitPolicyIdentity struct {
	Name  string `yaml:"name"`
	Email string `yaml:"email"`
}

CommitPolicyIdentity is one exact author/committer name and email pair.

type CommitPolicySigner added in v0.30.0

type CommitPolicySigner struct {
	Principal string `yaml:"principal"`
	Key       string `yaml:"key"`
}

CommitPolicySigner is one SSH signing principal and public key pair.

type Config

type Config struct {
	Prefix string `yaml:"prefix"`
	// 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"`
	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

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

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

func Parse(awfDir string, b []byte) (*Config, error)

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

func (c *Config) HasSidecar(kind, name string) (bool, error)

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

func (c *Config) NormalizedLocalDocs() []LocalDoc

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) PartPath

func (c *Config) PartPath(kind, artifact, section string) string

PartPath returns the convention part path for a section of an artifact.

func (*Config) ReadPart added in v0.22.0

func (c *Config) ReadPart(kind, artifact, section string) ([]byte, bool, error)

ReadPart returns selected-universe convention-part bytes.

func (*Config) ReadPartPath added in v0.22.0

func (c *Config) ReadPartPath(full string) ([]byte, error)

ReadPartPath reads a consumed absolute part path through the selected reader.

func (*Config) ReadSidecar added in v0.22.0

func (c *Config) ReadSidecar(rel string) ([]byte, bool)

ReadSidecar returns selected-universe sidecar bytes by config-relative path.

func (*Config) Sidecar

func (c *Config) Sidecar(kind, name string) (Sidecar, error)

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).

func (*Config) SidecarPath added in v0.44.0

func (c *Config) SidecarPath(kind, name string) string

SidecarPath returns a config-relative sidecar path.

func (*Config) Source added in v0.10.0

func (c *Config) Source() []byte

Source returns the exact config.yaml bytes Load read. A byte-level editor (SetArrayMember, SetArray, SetMappingScalar) reuses these instead of re-reading the file, which after a successful Load could only fail on a race.

func (*Config) Validate

func (c *Config) Validate() error

func (*Config) WithTree added in v0.41.0

func (c *Config) WithTree(read TreeReader) *Config

WithTree preserves parsed configuration facts and their source bytes while rebinding subsequent sidecar and part reads to one required operation tree.

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.

func NewFacts added in v0.40.0

func NewFacts(cfg *Config) (Facts, error)

NewFacts copies every reference-shaped configuration value and discards the loading representation. Validation remains the responsibility of Loaders.

func (Facts) Config added in v0.40.0

func (f Facts) Config() *Config

Config returns a defensive copy of the loaded configuration facts.

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.

func (*LocalDoc) UnmarshalYAML added in v0.36.0

func (d *LocalDoc) UnmarshalYAML(node *yaml.Node) error

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.

func (*LocalDocs) UnmarshalYAML added in v0.36.0

func (d *LocalDocs) UnmarshalYAML(node *yaml.Node) error

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

type MemoryExemption struct {
	Path  string `yaml:"path"`
	Count *int   `yaml:"count"`
}

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

type ScopeSpec struct {
	Name    string `yaml:"name"`
	Meaning string `yaml:"meaning"`
}

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.

func (*ScopeSpec) UnmarshalYAML added in v0.8.0

func (s *ScopeSpec) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML accepts either a scalar node (the bare-string form → empty meaning) or a strict mapping node. invariant: scope-config-dual-form

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.

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 SidecarEdit added in v0.44.0

type SidecarEdit struct {
	Field string
	Mode  string
	Value any
}

SidecarEdit describes one leaf-only YAML sidecar mutation.

type Skeleton

type Skeleton struct {
	Prefix string `yaml:"prefix"`
	// 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.

type TreeReader added in v0.22.0

type TreeReader interface {
	ReadFile(path string) ([]byte, bool)
	Paths(prefix string) []string
}

TreeReader supplies canonical config-tree-relative bytes without exposing a filesystem. Implementations return defensive copies.

Jump to

Keyboard shortcuts

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