synthesizer

type Block struct {
	// Title is the subsection heading the framework will generate for the
	// block (e.g. "Example d'appel (Postman) - minimal"). The framework
	// prepends the heading level matching the parent section.
	Title string

	// Language is the fenced-code info string used in the generated markdown
	// fence (e.g. "http+json", "sql", "bash", "mermaid"). Empty for prose
	// blocks (not used in MVP v1).
	Language string

	// Content is the block's body WITHOUT the fence. The framework wraps it
	// with the fence markers when rendering. Must be canonical and
	// deterministic: byte-identical for equal inputs across runs (I6).
	Content string

	// Notes is an ordered list of caveat lines appended under the fenced
	// block as a bullet list ("- note"). Typical content: server-injected
	// fields, degraded mode disclosure, variable convention reminders.
	Notes []string

	// InsertAfterHeading identifies where in the doc the block belongs.
	// Value matches a Section.Heading verbatim (same text, same hashes).
	// An empty value means "end of doc" - never used in MVP v1.
	InsertAfterHeading string
}

type Candidate struct {
	// Key is a stable, unique-per-doc identifier for this candidate (e.g.
	// "POST /api/account-statement/search"). Used for diff-per-section
	// routing and idempotency signatures.
	Key string

	// Anchor is the primary evidence span - typically the endpoint declaration
	// line for api-postman, the schema table row for sql-query, etc.
	Anchor Evidence

	// Extra carries synthesizer-specific data from Detect to Synthesize. The
	// framework treats it as opaque; concrete synthesizers own its schema.
	Extra map[string]any
}

type Config struct {
	// WellKnownServerFields is the list used by synthesizers to filter
	// likely server-injected fields when the source doc has no Security
	// section (I5-bis). Editable in AngelaConfig.Synthesizers.
	WellKnownServerFields []string

	// PerSynthesizer is a bag of synthesizer-specific options keyed by
	// synthesizer Name. Implementations look up their own key; unknown
	// keys are ignored by design (allows shipping options before the
	// synthesizer that reads them).
	PerSynthesizer map[string]map[string]any
}

type ContractFixture struct {
	// Name identifies the case in test output (e.g.
	// "complete-with-security", "no-security-section").
	Name string

	// Path is the synthetic file path attached to the parsed Doc.
	Path string

	// Content is the raw markdown (frontmatter + body) the framework will
	// parse with ParseDoc.
	Content string

	// ServerInjected lists the field names the doc explicitly declares as
	// server-injected (typically extracted from the Security section). The
	// I5 contract asserts NONE of these appear in the synthesizer's
	// Evidence.Field list. Empty when the fixture has no Security section.
	ServerInjected []string

	// WellKnown is the list passed to Config.WellKnownServerFields when
	// running this fixture. The I5-bis contract uses this list to assert
	// the degraded mode filter actually fires.
	WellKnown []string

	// ExpectMissingSecurity declares whether this fixture lacks a Security
	// section. When true, the I5-bis contract is exercised: every
	// Synthesize call MUST emit a Warning with Code ==
	// WarningCodeMissingSecuritySection.
	ExpectMissingSecurity bool

	// MinCandidates is the minimum number of Candidates Detect must return
	// for this fixture. Zero disables the check.
	MinCandidates int
}

type Doc struct {
	// Path is the source file path, relative to the corpus root when known,
	// absolute otherwise. Used for evidence File references.
	Path string

	// Meta is the parsed YAML frontmatter. Synthesized (from the frontmatter
	// "synthesized" key) is surfaced separately via Signatures because it is
	// not part of domain.DocMeta yet.
	Meta domain.DocMeta

	// Body is the markdown content AFTER the frontmatter terminator.
	Body string

	// Lines is Body split on "\n", 1-indexed at Lines[1]. Lines[0] is empty
	// to make line numbers cited in Evidence directly indexable.
	Lines []string

	// Sections is the flat list of top-level and sub-level headings found in
	// Body, in source order. Synthesizers use FuzzyFindSection (task 5) on
	// this slice rather than re-parsing.
	Sections []Section

	// Signatures holds previously-recorded synthesizer signatures, keyed by
	// synthesizer Name. Empty when the doc has never been synthesized. The
	// registry compares current evidence hashes against these to decide
	// skip vs regenerate (I6).
	Signatures map[string]Signature
}

type EnabledConfig struct {
	// Enabled is the ordered list of synthesizer names to activate. Empty
	// means "no synthesizers this run" (the default before 8-18 merges;
	// after 8-18, defaults.go sets this to ["api-postman"]).
	Enabled []string

	// Disabled forces all synthesizers off, overriding Enabled. Mapped from
	// the --no-synthesizers CLI flag.
	Disabled bool
}

type Evidence struct {
	// Field is the output key this evidence supports (e.g. "month",
	// "creditAmountMin"). Empty for anchor-only evidences attached to
	// Candidates and Warnings.
	Field string

	// File is the source file path, matching Doc.Path when the evidence
	// comes from the doc being synthesized. Different for cross-file
	// evidence (not used in MVP v1).
	File string

	// Line is the 1-based line number. ColStart/ColEnd are byte offsets
	// into that line.
	Line     int
	ColStart int
	ColEnd   int

	// Snippet is the literal source text at File:Line[ColStart:ColEnd]. The
	// framework validates Snippet == doc.Lines[Line][ColStart:ColEnd] before
	// accepting the evidence.
	Snippet string

	// Rule is the reason the evidence is valid. MVP v1 accepts only
	// "literal". Future relaxations would introduce
	// alternative rules with their own invariants.
	Rule string
}

type FixtureReport struct {
	Results map[string]error
}

type OrderedMap struct {
	// contains filtered or unexported fields
}

type Registry struct {
	// contains filtered or unexported fields
}

type Section struct {
	// Heading is the heading text WITH leading hashes, e.g. "### Endpoints".
	Heading string

	// Level is the heading depth (1 for #, 2 for ##, ...).
	Level int

	// Title is Heading without the leading "#+ " prefix.
	Title string

	// StartLine is the 1-based line number of the heading itself.
	StartLine int

	// EndLine is the 1-based line number of the last line BEFORE the next
	// heading at the same or shallower level (exclusive upper bound
	// rendered as inclusive line number - the line is part of this section).
	EndLine int

	// Content is the raw content between the heading and EndLine (excluding
	// the heading line). Trailing newline trimmed.
	Content string
}

type Signature struct {
	// Hash is a hex-encoded sha256 over the canonical list of evidence
	// spans (File, Line, ColStart, ColEnd, Snippet) the synthesizer used.
	// Evidence-based, not output-based: the hash remains stable across
	// cosmetic output tweaks and shifts only when source spans change.
	Hash string `yaml:"hash"`

	// At is the RFC3339 timestamp of the last successful Synthesize call
	// that produced output matching this signature.
	At string `yaml:"at"`

	// Version is the synthesizer's own output-format version. Bumped when a
	// backward-incompatible output change ships; forces regeneration even
	// when the source evidences are unchanged.
	Version string `yaml:"version"`

	// Sections is the ordered list of source section titles consulted for
	// this synthesis. Purely informational; not part of Hash.
	Sections []string `yaml:"sections,omitempty"`

	// EvidenceCount is the number of Evidence records backing the output.
	// Informational, for audit visibility in frontmatter diffs.
	EvidenceCount int `yaml:"evidence_count"`

	// Warnings is the list of Warning.Code values emitted for this run. Used
	// by the review hook to avoid re-emitting findings already present in
	// the frontmatter and by audits to spot docs shipped in degraded mode.
	Warnings []string `yaml:"warnings,omitempty"`
}

type Synthesizer interface {
	// Name is the stable identifier used in config, frontmatter signatures and
	// CLI flags (e.g., "api-postman", "sql-query"). Must be lowercase kebab-case.
	Name() string

	// Applies is a fast, side-effect-free gate. It returns true when the doc
	// looks like a candidate for this synthesizer (frontmatter type, presence
	// of characteristic sections, regex hits). It must NOT parse the body in
	// depth - Detect does that.
	Applies(doc *Doc) bool

	// Detect enumerates synthesis opportunities inside the doc. Each Candidate
	// carries a primary anchor (evidence span) and any synthesizer-specific
	// extras needed to later synthesize without re-parsing. Detect may return
	// an empty slice and nil error when the doc applies but has no candidate
	// (e.g., endpoints section present but empty).
	Detect(doc *Doc) ([]Candidate, error)

	// Synthesize turns a Candidate into a ready-to-insert Block plus the list
	// of Evidences supporting every field in the block's output and any
	// non-fatal Warnings (degraded mode, fuzzy heading match, etc.).
	//
	// The contract for I4 lives here: every output key produced by the
	// synthesizer must appear at least once in the returned []Evidence with
	// Rule == "literal" and Snippet equal to the source file content at the
	// declared span.
	Synthesize(c Candidate, cfg Config) (Block, []Evidence, []Warning, error)
}

type Warning struct {
	// Code is a short, stable identifier ("missing-security-section",
	// "fuzzy-heading-match", "endpoints-without-field-source"). Used as the
	// finding category and as a lookup key in severity_override.
	Code string

	// Message is a human-readable explanation localized by the framework at
	// render time. Concrete synthesizers emit the CODE only; the
	// framework's i18n layer translates.
	Message string

	// Line is the 1-based line number the warning attaches to, or 0 when it
	// is doc-scoped (e.g. missing-security-section is doc-scoped).
	Line int
}