Documentation
¶
Overview ¶
Package render parses awf section markers and renders templates with per-project overlays via text/template.
Index ¶
- Constants
- func CheckResidualMarkers(assembled string) error
- func CheckResidualMarkersSource(assembled SourceText) error
- func CheckSectionDefaultStubs(segs []Segment, plan map[string]SectionPlan) error
- func Execute(assembled string, data map[string]any, parts map[string]string, name string) (string, error)
- func ExecuteSourceWithTemplateSource(assembled SourceText, data map[string]any, parts map[string]string, ...) (string, error)
- func ExpandIncludes(src string, partialFS fs.FS) (string, error)
- func ExtractStructuralHeadings(output string, tokens map[string][2]string) (map[string]string, error)
- func HasMarkerLine(body string) bool
- func HasStubMarker(body string) bool
- func PlaceholderVarRefs(body string) []string
- func PointerLinePrefixes(name string, style CommentStyle) []string
- func ReferencedDataKeys(src string) []string
- func ReferencedVars(src string) []string
- func ReferencesBareData(src string) bool
- func ReferencesBareVars(src string) bool
- func ReferencesCommitPolicy(src string) bool
- func ReferencesScopePlaceholder(body string) bool
- func ReferencesScopes(src string) bool
- func StripAuthoringComments(src string) (string, error)
- func StructuralHeadingCapture(segs []Segment) (string, map[string][2]string)
- func StubSections(segs []Segment, plan map[string]SectionPlan) (defaults, parts []string)
- type CommentStyle
- type SectionPlan
- type Segment
- type SourceSpan
- type SourceText
- type TemplateSource
Constants ¶
const SectionDefaultSentinel = "\x00awf:section-default\x00"
SectionDefaultSentinel is the brace-free, NUL-delimited token the project layer substitutes for the {{=awf:sectionDefault}} placeholder (ADR-0072). Assemble splits a part body at each occurrence and splices the section's raw default source between the verbatim fragments, so Execute renders the default in place. Brace-free (inert to the template parser) and NUL-delimited (cannot collide with template or markdown text).
Variables ¶
This section is empty.
Functions ¶
func CheckResidualMarkers ¶ added in v0.10.0
CheckResidualMarkers hard-errors when an assembled skeleton still contains a marker-shaped awf:section/awf:end token - a malformed marker (unknown attribute, missing name) that ParseSections could not consume and that would otherwise leak verbatim into rendered output. It runs pre-Execute: part bodies are NUL sentinels and data is uninterpolated, so parts and data that quote the full comment form stay out of scope. touches-state: rendering/render-engine:no-residual-section-marker - hard error on surviving marker residue; proof in section_test.go
func CheckResidualMarkersSource ¶ added in v0.34.0
func CheckResidualMarkersSource(assembled SourceText) error
CheckResidualMarkersSource applies the structural residue guard only to renderer-owned template spans. Empty-source spans are raw convention or adopter-owned in-place bytes and remain verbatim by contract.
func CheckSectionDefaultStubs ¶ added in v0.11.0
func CheckSectionDefaultStubs(segs []Segment, plan map[string]SectionPlan) error
CheckSectionDefaultStubs hard-errors when a part re-injects the default of a stub-attributed section (ADR-0072 Decision 4): a stub default is an authoring prompt, not shippable prose, so there is nothing valid to re-inject and the section must stay in must-author state. Runs pre-Assemble on the same segs+plan StubSections consumes; it scans the substituted part body for the render-layer sentinel, since planSections has already replaced the {{=awf:sectionDefault}} token.
func Execute ¶
func Execute(assembled string, data map[string]any, parts map[string]string, name string) (string, error)
Execute runs text/template over the awf-owned skeleton (part bodies stood in by sentinels) under missingkey=zero, then restores each raw part body verbatim - so a convention part is never parsed or executed as a template. name labels parse and execute errors with the target rather than a hardcoded literal. touches-state: rendering/render-engine:parts-raw-except-authoring-comments - part bodies restored verbatim post-strip, never templated; proof in render_test.go
func ExecuteSourceWithTemplateSource ¶ added in v0.34.0
func ExecuteSourceWithTemplateSource(assembled SourceText, data map[string]any, parts map[string]string, name string, provenance TemplateSource) (string, error)
ExecuteSourceWithTemplateSource executes an assembled source while deriving markers from the bytes that survive template control flow. Instrumenting the parsed tree preserves controls that cross source-span and section boundaries.
func ExpandIncludes ¶ added in v0.6.2
ExpandIncludes replaces each directive with its partial body. It remains the compatibility projection for callers that do not need regional provenance.
func ExtractStructuralHeadings ¶ added in v0.31.0
func ExtractStructuralHeadings(output string, tokens map[string][2]string) (map[string]string, error)
ExtractStructuralHeadings recovers each heading captured during execution.
func HasMarkerLine ¶ added in v0.12.0
HasMarkerLine reports whether body contains a line that, after trimming, begins with a marker-shaped `awf:section`/`awf:end` comment opener - the ADR-0083 whole-line detection behind the part-marker advisory. The prefix anchor covers the exact closed marker, an unclosed opener, and a marker with trailing text: none has a legitimate quoter, since prose quoting the form always precedes it on the line. Inline quoting never fires; the awf:stub part marker is out of scope by construction (the pattern names only section/end). Callers exclude fenced code before the scan. touches-state: rendering/render-engine:part-marker-advisory - whole-line section-marker residue detection; proof in section_test.go
func HasStubMarker ¶ added in v0.10.0
HasStubMarker reports whether a part body contains a line that is exactly the awf:stub marker (modulo surrounding whitespace). Detection never mutates the body - parts render byte-for-byte verbatim, marker included (ADR-0034, ADR-0070). touches-state: rendering/render-engine:stub-part-verbatim - stub-marker detection without mutation; proof in section_test.go
func PlaceholderVarRefs ¶ added in v0.13.0
PlaceholderVarRefs returns the config vars a raw convention-part body consumes through {{=awf:key}} placeholders - gateCmd and checkCmd are the only registry keys that read vars (see project.placeholderRegistry). Scanned on the on-disk bytes: substitution has already replaced the tokens in the assembled output, so this is the one consumption channel the assembled-source scan cannot see (ADR-0086 Decision 3). A backslash-escaped token (ADR-0058) renders literally and reads no var, so it is stripped before matching.
func PointerLinePrefixes ¶ added in v0.18.0
func PointerLinePrefixes(name string, style CommentStyle) []string
PointerLinePrefixes returns the awf:edit-family pointer line prefixes (the awf:edit and awf:edit-in-place variants) for a section named `name` in the given comment style, up to and including the `: ` separator. Every editPointer variant emits `<open>awf:edit[-in-place] <name>: ...`, so a trimmed output line is that section's pointer iff it begins with one of these prefixes. Read-back matches a region boundary by these exact per-section strings, never a generic pointer shape, so adopter text resembling a pointer for a non-registered name cannot bound a region (ADR-0100 Decision 2 / in-place-readback).
func ReferencedDataKeys ¶ added in v0.13.0
ReferencedDataKeys returns the sorted, de-duplicated list of top-level sidecar data keys referenced via {{ .data.K }} patterns in src (ADR-0086). Nested access (.data.a.b) claims its top-level key.
func ReferencedVars ¶
ReferencedVars returns the sorted, de-duplicated list of variable names referenced via {{ .vars.X }} patterns in src.
func ReferencesBareData ¶ added in v0.13.0
ReferencesBareData reports whether src reads .data without a key selector (range/with/index or a whole-map reference). Key-level extraction cannot see through such access, so it conservatively marks every data key consumed (ADR-0086 Decision 4). No shipped template uses the form; this is the future-proofing escape.
func ReferencesBareVars ¶ added in v0.13.0
ReferencesBareVars mirrors ReferencesBareData for the vars namespace (ADR-0086 Decision 3).
func ReferencesCommitPolicy ¶ added in v0.30.0
ReferencesCommitPolicy reports whether a non-comment template action reads the typed commit-policy render context.
func ReferencesScopePlaceholder ¶ added in v0.8.0
ReferencesScopePlaceholder reports whether a raw convention-part body uses a {{=awf:commitScope*}} sandbox placeholder (ADR-0057), so the artifact folds the resolved scope list into its config hash and reflags on a scopes edit.
func ReferencesScopes ¶ added in v0.6.0
ReferencesScopes reports whether src reads the resolved commit-scope render context (any {{ ... .commitScopes ... }} action) - such templates fold the resolved scope list into their config hash (ADR-0051).
func StripAuthoringComments ¶ added in v0.18.0
StripAuthoringComments removes whole-line awf:comment authoring directives from src: a line whose trimmed form opens with the exact commentOpen literal at a token boundary (followed by a space, a tab, "-->", or the end of the line) and ends with "-->" is removed together with its trailing newline. Fenced code blocks are preserved verbatim, so a part or template can demonstrate the syntax. A whole line outside a fence that opens at the boundary but does not end with "-->" - a missing close, the bare opener, or text trailing the close - is a hard error; the input is returned unchanged alongside it. Mid-line occurrences and prefix-sharing tokens (awf:commentary) never fire.
func StructuralHeadingCapture ¶ added in v0.31.0
StructuralHeadingCapture returns a marker-free copy of the complete template skeleton with each structural heading bracketed by inert tokens. Executing this source preserves the template parse tree's surrounding variables, dot, and control flow while exposing the rendered heading lines to the project layer.
func StubSections ¶ added in v0.10.0
func StubSections(segs []Segment, plan map[string]SectionPlan) (defaults, parts []string)
StubSections reports a parsed template's unauthored stub content under a plan (ADR-0070): defaults = stub-attributed sections rendering their template default; parts = sections whose convention part carries the awf:stub marker. Dropped sections report nothing.
Types ¶
type CommentStyle ¶ added in v0.18.0
type CommentStyle int
CommentStyle is the comment syntax a rendered target uses for the surviving awf:edit-family provenance pointers. Because the pointers survive into output as comments, they must be valid comments in the target's language (ADR-0100 Decision 7): a `#`-line comment for a `#!`-shebang target such as a shell script, an HTML comment otherwise. The zero value is HTMLComment, the historical default.
const ( HTMLComment CommentStyle = iota // <!-- <text> --> HashComment // # <text> SlashComment // // <text> )
func CommentStyleForSource ¶ added in v0.18.0
func CommentStyleForSource(src string) CommentStyle
CommentStyleForSource picks the pointer comment style for a target from its (expanded) template source, by the same `#!`-shebang sniff injectBanner uses so the pointer emitter and the read-back matcher derive the style identically and cannot diverge (ADR-0100 Decision 7).
type SectionPlan ¶
type SectionPlan struct {
Drop bool
HasPart bool
PartBody string
// PartStub marks a part body carrying the whole-line awf:stub marker -
// declared-unauthored starter content (ADR-0070). Set by the project layer,
// which reads part bodies; consumed by StubSections.
PartStub bool
// PartMarker marks a part whose raw, fence-excluded body carries a
// whole-line section-marker residue (ADR-0083). Set by the project layer
// over the on-disk bytes - pre placeholder substitution, whose multi-line
// values must never create or mask a match; consumed part-keyed by the
// marker advisory.
PartMarker bool
// PartVarRefs lists the config vars the raw part body consumes via
// {{=awf:key}} placeholders (ADR-0086). Set by the project layer over
// the on-disk bytes; consumed by the unused-var union, which cannot see
// part bodies in the assembled source (they are sentinel-substituted raw).
PartVarRefs []string
EditPath string
// InPlace marks a section whose body the adopter edits directly in the
// rendered output, preserved across syncs (ADR-0100). Mutually exclusive
// with HasPart. InPlaceFound reports whether the section's region was located
// in the existing output (its pointer was present); InPlaceBody is that
// region's read-back content (possibly empty - an adopter may empty the
// region). When InPlaceFound is false (first render / deleted pointer) the
// template default renders instead; a found-but-empty region stays empty, so
// emptying a region is not silently reverted to the default (ADR-0100 Decision 2).
InPlace bool
InPlaceFound bool
InPlaceBody string
}
SectionPlan is the project layer's per-section resolution handed to Assemble. Exactly one of Drop / HasPart / (neither) holds: Drop omits the section, HasPart substitutes PartBody, neither renders the template default. EditPath is the project-relative convention part path named by the awf:edit pointer.
type Segment ¶
type Segment struct {
IsSection bool
Name string
// Source is the ordered literal or default-body source. SectionSource is
// the root template identity of a structural section; convention parts are
// deliberately not represented here.
Source SourceText
SectionSource string
Text string
// Heading is the optional awf-owned Markdown ATX heading at the section's
// leading structural position. It is deliberately separate from the body.
Heading string
HeadingSource SourceText
// Stub marks a section whose template default is a must-replace authoring
// prompt, declared by the `stub` marker attribute (ADR-0070).
Stub bool
// InPlace marks a section declared by the `inplace` marker attribute
// (ADR-0100); its body is read back from the rendered output rather than a
// convention part, and preserved across syncs. Mutually exclusive with Stub.
InPlace bool
}
func ParseSourceSections ¶ added in v0.34.0
func ParseSourceSections(src SourceText, markdown ...bool) []Segment
ParseSourceSections splits source-aware text into ordered literal and section segments while retaining literal and default-body spans. Structural section identity is always the root template, because included partials are forbidden from carrying section markers.
type SourceSpan ¶ added in v0.34.0
type SourceSpan struct {
Source string
Text string
// Provenance is the effective template identity emitted for surviving
// rendered bytes. It is populated during assembly and excluded from the
// authored-text projection used by template hashes.
Provenance string
}
SourceSpan is one ordered authored region and its template identity. Empty Source identifies renderer-generated or convention-part text, which must not acquire template provenance.
type SourceText ¶ added in v0.34.0
type SourceText struct {
Root string
Spans []SourceSpan
}
SourceText retains the root template identity and each ordered authored span. Its AuthoredText projection is the byte-for-byte input used for template hashes.
func AssembleSourceWithTemplateSource ¶ added in v0.34.0
func AssembleSourceWithTemplateSource(segs []Segment, plan map[string]SectionPlan, style CommentStyle, provenance TemplateSource) (SourceText, map[string]string)
AssembleSourceWithTemplateSource applies section assembly and emits source transitions when template provenance is enabled. touches-state: rendering/render-engine:no-section-marker-leak - structural directives remain excluded while template-source markers are renderer-owned; proof in render_test.go touches-state: rendering/render-engine:template-source-symbol - root, include, return, and structural-section marker emission; proof in render_test.go and project/template_source_marker_test.go
func ExpandIncludesSource ¶ added in v0.34.0
func ExpandIncludesSource(src, root string, partialFS fs.FS) (SourceText, error)
ExpandIncludesSource replaces directives while retaining the root template and each included partial as distinct ordered spans.
func StripAuthoringCommentsSource ¶ added in v0.34.0
func StripAuthoringCommentsSource(src SourceText) (SourceText, error)
StripAuthoringCommentsSource removes authoring directives while retaining each kept byte range's source span. It never coalesces adjacent spans, since an include boundary remains meaningful even when a comment is stripped nearby.
func (SourceText) AuthoredText ¶ added in v0.34.0
func (s SourceText) AuthoredText() string
AuthoredText flattens the ordered source spans without changing their bytes.
type TemplateSource ¶ added in v0.34.0
type TemplateSource struct{ Root string }
TemplateSource enables renderer-owned regional template provenance. Root is a normalized repository-relative directory; an empty Root preserves historical output exactly.
Source Files