feat: add structural tree parser for conditional-aware spec editing

[trungams]

Summary

Replaces the flat Visit-based spec line walker with a structural tree parser for all spec editing operations. This makes conditional-boundary bugs structurally impossible and fixes several long-standing issues (#144, #193, #203).

Closes #214

Changes

New: tree parser (tree.go)

Two-pass parser that builds a block tree from raw spec lines:

• Pass 1: collects %if/%endif pairs, skipping pairs inside %define/%global macro continuation bodies
• Pass 2: builds nested block tree, classifying conditionals as wrappers (contain section headers) vs content blocks

Block kinds: rootBlock, sectionBlock, conditionalBlock, textBlock, macroDefBlock. Lossless round-trip via serializeTree.

New: tree API (tree_api.go)

specTree / sectionHandle types wrap the parsed tree. Spec.mutateTree handles parse → mutate → serialize; Spec.inspectTree for read-only access. The public Spec.* API is unchanged for callers.

New: SearchAndReplace rewrite (searchReplaceBlock)

Dedicated recursive walker that visits ALL line types (text, macros, conditional headers, %endif). The old VisitAllLines-based implementation skipped %define/%global and conditional directive lines. Also relaxes the section filter for wrapper else-branch content.

New: macro hoisting (tree_hoist.go)

RemoveSections now automatically hoists %define/%global macros from removed sections when they're referenced by surviving content (#203). Scans for %{name}, %{?name}, %{!?name}, bare %name, and conditional headers like %if 0%{?with_name}.

New: GetTag and PrependLinesToAllSections

• GetTag(packageName, tag) — read-only tag lookup via inspectTree, replaces VisitTagsPackage usage
• PrependLinesToAllSections + spec-prepend-all-lines overlay — prepends to every matching section (used by check-skip to disable all %check sections)

New: testdata fixtures + synthetic stress

13 curated .spec fixtures distilling real-world patterns. Two test tiers (lossless round-trip + per-pattern edit-operation regression). Synthetic generator with 64+32 deterministic seeds.

Removed: Visit infrastructure

Visit, VisitTags, VisitTagsPackage, Context, VisitTarget, VisitTargetType, Visitor, parseState, parseSpecLine, newParsedLine, parseLogicalLine — all deleted. The sole external caller (release.go) migrated to GetTag.

Also removed: sectionLineRange, collectSectionRanges, balanceRange, validateNoContentAfter, skipPastConditional, findInsertTagPosition, isBlankOrComment, removeRanges, and related helpers.

Docs

• RFC 001 added to docs/developer/rfc/
• Known limitations documented in docs/user/reference/config/overlays.md

Validation

Full render against Azure Linux 4.0 (~7,400 components):

Metric	Baseline	This PR	Delta
Wall time	24m 11s	22m 59s	-5.0%
CPU (user)	303m 34s	277m 07s	-8.7%
Render failures	0	0	—

Rendered output: tvuong/4.0/feat/azldev-parsetree

Known limitations

1. Straddling sections — section header inside %if wrapper with content past %endif is invisible to section-scoped overlays. Workaround: spec-search-replace. Affects 1 spec (gdb).
2. Macro-generated sections — sections from %ghc_lib_subpackage, %fontpkg, etc. are invisible to the static parser.

[trungams]

The gdb render failure in e2e is expected as we'll need to update the overlay

[dmcilvaney]

Could we add some mechanism to control which branch we go down? For example, many specs have something like

%if <condition>
Release: 1
%else
Release: %autorelease
%endif

It would be nice to be able to target one.
Maybe a mode enum? Something like First, All, SpecificN, RequireUnique maybe?

This could apply generally to both read and write operations.

[trungams]

It's definitely possible since each branch will be its own block. My question is whether we want to allow users to select branches based on condition (requires evaluation) or just ordering of the branches. Also how should we target these conditional blocks, since there may be multiple with similar conditions in the same spec file.

[dmcilvaney]

Is there a way to map the blocks back to the line numbers? Maybe have each block have a line offset inside its parent? That would provide a very basic way to find First and SpecificN (if we even WANT that one) based on sorting. All just applies everywhere (I think this is sort of the implicit default right now), and RequireUnique just errors out if there is any ambiguity.

[dmcilvaney]

Probably out of scope for this doc, but curious how we might handle recursive definitions

%define a %{b}
%define b some_value

If I understand the algorithm right we would move %define a %{b} to the global scope, but might now have a dangling link to %{b}.

[dmcilvaney]

Also, should hoisting be an opt-in flag, or on by default? Direction I've been getting is "no magic" because it gets confusing to reason about. Randomly moving variables might be surprising. If the flag is instead a list, would also fix the recursive definition thing above.

[dmcilvaney]

This pattern seems to repeat a bunch, thoughts on making a walkBlocks() function, or at least an interface.

func collectMacrosInSections(sections []*block) []*block {
    var macros []*block
    for _, sec := range sections {
        walk(sec, func(b *block) bool {
            if b.Kind == macroDefBlock {
                macros = append(macros, b)
            }
            return true
        })
    }
    return macros
}

Mutating funcs (removeBlocKFromParent etc.) feel harder, maybe leave them as-is?