Package: filter

builtInVars are always available in the filter scope regardless ofschema declarations. id and title live on model.Node, not inAttrs; the rest are the RFC §2.3 built-in attributes (status,disposition, trace, version). They are always accepted by the typocheck even when no schema in the tree declares them; at evaluation timea requirement lacking the attribute sees nil (see AllowUndefinedVariables).

exprBuiltins is the set of expr built-in function names that are NOTvariable references. We exclude them from attribute validation so thatid startsWith "SYS-" or len(variant) > 0 don't trip the typo check.

Filter is a compiled attribute filter expression. It is safe forconcurrent use after construction — the underlying vm.Program isread-only.

Compile parses, validates, and compiles a filter expression (strictmode).

validAttrs is the union of all schema property names (plus built-invariable names) across every document in the tree. Referencing a namenot in this set is a compile-time ERROR — this catches typos andreferences to attributes that no document declares.

The expression is compiled with AllowUndefinedVariables so that arequirement whose document does not declare a referenced attributeevaluates that variable to nil (the req is excluded unless theexpression handles absence, e.g. variant == null).

CompileRelaxed compiles a filter expression without hard-failing onattribute names that are not declared in any schema.yaml. validAttrs isthe expanded allowed set (schema-declared names plus every attributeactually found on a requirement); declaredAttrs is the schema-declaredset plus built-ins and drives which references produce a warning. Everyreferenced name outside declaredAttrs yields a warning instead of anerror, so undeclared-but-present attributes become filterable while truetypos no longer abort the run.

compile is the shared implementation for strict and relaxed modes.strict=true returns an error for any referenced name outside validAttrs(the global typo check). strict=false never errors on unknown names;instead every name outside declaredAttrs is collected as a warning.

buildEnv constructs the expr evaluation environment for a requirement:the req's Attrs map plus id and title injected as top-level vars.We copy into a new map to avoid mutating the original Attrs.

BuildValidAttrs computes the union of all schema property names acrossevery document plus the built-in variable names. The result is used byCompile for strict attribute validation.

BuildFoundAttrs computes the union of every attribute key actuallypresent on some requirement in the tree, whether or not it is declaredin a schema.yaml. Relaxed filtering unions this with BuildValidAttrs soundeclared-but-present attributes can be filtered.

WriteWarnings writes relaxed-mode filter warnings to w, one per line,prefixed with "reqmd: warning: ". It is a no-op when warnings is emptyso callers can invoke it unconditionally.

CompileForDocs compiles an expression against the attribute union of thegiven documents. It is the shared entry point for every CLI command thataccepts a --filter flag: Compile + BuildValidAttrs in one call.

When allowUndeclared is false the strict typo check applies and anyreference to an attribute not declared in a schema.yaml is an error.When true, references to attributes found on any requirement are allowed(undeclared-but-present) and every out-of-schema reference is returned asa warning instead of an error. Returns (nil, nil, nil) when expr is empty.

refCollector implements ast.Visitor and collects all IdentifierNodevalues from the expression AST. These are cross-referenced againstvalidAttrs to catch typos.

undeclaredDocs is testDocs plus a requirement carrying an attribute thatno schema declares (owner), the relaxed-filtering scenario.

TestCompileForDocs_StrictRejectsUndeclared pins the default behavior: theglobal typo check rejects attributes that no schema declares.

TestCompileForDocs_RelaxedAllowsFoundAttr is the relaxed-filter contract:an attribute present on a requirement becomes filterable even though noschema.yaml declares it, and the deviation is reported as a warning.

TestCompileForDocs_RelaxedWarnsOnTrulyUnknown verifies relaxed mode turnsa genuine typo into a warning instead of aborting the run.

TestCompileForDocs_RelaxedDeclaredAttrNoWarning keeps relaxed mode quietfor expressions that only use declared attributes.

TestCompileForDocs_EmptyExpression asserts the no-filter fast path.