Large KiCad files often need narrow source scans before full tree or OOP parsing would be justified.
Describe generic S-expression form selection by head, exact path, depth, and pruned subtrees.
Tests must prove head, path, depth, and prune filters select the intended forms without materializing unrelated forms.
A selector is public when PCB, schematic, and library scanners can reuse it without file-type-specific regex logic.
Projection callers need stable source ranges that can be inspected, reparsed, or mapped to diagnostics without keeping a full parse tree.
Represent one complete selected S-expression form with head, path, depth, offsets, source location, and helpers for text and parse access.
Tests must prove selected span text is exact, offsets are stable, and reparsing the span produces the selected form.
A span is public when downstream scan tools can safely defer full parsing until a selected form is actually needed.
OOP model callers need one predictable query view for schematics, boards, footprints, projects, and designs instead of ad hoc list traversal.
Provide a read-only live sequence with type/name filtering, exact-attribute filtering, count, first, and materialization helpers.
Tests must prove the collection is sequence-like, live, filterable by class and class name, and rejects direct mutation.
A model-owned collection facade is public when it supports common query helpers without owning or mutating the underlying model list.