rfw_catalog_compiler library

Public entry point for the Remote Flutter Widget catalog compiler.

The compiler's full internal IR lives under src/ir; selected walker and lowering entry points are exported for reflector integration.

Classes

AddMemberWireIdEvent

Event that adds a structured member to a union.

AllocWireIdEvent

Event that allocates a new wire ID.

CatalogChange

One detected per-entry change between two canonical catalog versions.

CatalogDiffReport

The full result of diffing two canonical catalog versions: every detected change with its classification, plus the emitted CompatRules.

CategoryHeuristics

Heuristic rules for property category inference.

CategoryRule

One category inference rule.

ClassifiedChange

A detected CatalogChange paired with its compatibility classification.

CrossRefResolutionIndex

Plain-data cross-reference resolution keys captured before lowering.

DenylistFilter

Pure type predicate. Stateless and depth-agnostic so it can walk analyzer type structures without depending on the rest of the compiler.

DenylistMatch

A type predicate's verdict. Null means "allowed". A non-null value names which category of the DenylistPolicy matched and carries a human-readable reason for the audit trail.

DenylistPolicy

Type-, type-suffix-, widget-, and per-class-property exclusions.

DeprecateWireIdEvent

Event that marks an entry as deprecated.

DesignTokenHeuristics

Heuristics that map property-name patterns to design-token wire IDs.

DiagnosticIR

One internal compiler diagnostic attached to IR.

EntryAdded

A new entry appeared in the new catalog version. Additive — no existing blob references it.

EntryDeprecated

An entry gained a catalog-lifecycle deprecation — deprecated.catalog is present in the new version and absent in the old. Additive — blobs continue to resolve; the editor warns.

EntryRemoved

An entry present in the old version is absent from the new version. Breaking — blobs referencing the wire ID no longer resolve.

EntryRenamed

An entry's advisory label (display name, source path, or variant accessor) shifted while its wire ID stayed stable. Free under wire IDs.

EntryReplaced

An entry gained a successor via a replace event — its deprecated.catalog.replaceWith is present in the new version. Forwarding — the decoder remaps old references to successor.

LibraryWalkResult

Result of walking a barrel library for an @RestageLibrary declaration.

MutexPolicy

Mutually-exclusive property groups, keyed by widget flutterType.

PolicyDecisionIR

One compiler policy decision retained for audit trails.

PolicyLedger

Immutable bag of every compiler policy. Constructed once per compile pass and threaded through the analysis pipeline.

PriorityHeuristics

Heuristic settings that control property-priority ordering.

PropertyDefaultChanged

A property's or structured field's defaultSource changed — including a null ↔ non-null transition or a change of DefaultValueSourceKind. Additive — blobs carrying an explicit value are unaffected.

PropertyMetadataChanged

A property's editor metadata (category / priority) changed. Additive — editor-surface metadata only.

PropertyTypeChanged

A property's or structured field's catalog PropertyType changed. Always kind == WireIdKind.property.

RenameWireIdEvent

Event that renames an existing wire-ID-backed entry.

ReplaceWireIdEvent

Event that links an entry to its successor.

RequiredFlagChanged

A property's or structured field's required flag flipped.

RestageCatalogGenAdapter

Adapter from restage_catalog_gen's reflected schema entries into compiler IR.

RestageCatalogGenEventLogWireIdResolver

Replayed event-log resolver for restage_catalog_gen's adapter.

RestageCatalogGenWireIdHooks

Optional wire-ID hooks for the transitional restage_catalog_gen adapter.

RestageLibraryDeclaration

The declared identity of a customer widget library.

StabilityPolicy

Stability-tier rules for catalog entries.

StructuredWalkPolicy

Whitelist + abstract-base list governing how the compiler recurses into structured value types (e.g. BoxDecoration, TextStyle).

StructuredWalkResult

Result of walking one structured type entry point.

SyntheticStrategyChanged

A property's synthetic codegen strategy changed. Breaking — the decoder semantics for the slot shift.

ThemeBindingSeeds

(widget-name, property-name) → ThemeBindingPath seeds for theme-binding inference.

TokenFallbackChanged

A design token's literalFallback changed. Additive — same render-time resolution contract as a resolver change.

TokenResolverChanged

A design token's resolver (theme-binding path) changed. Additive — existing blobs see the new resolved value at render time.

TokenTypeChanged

A design token's DesignTokenType changed. Breaking — properties referencing the token may have type-mismatched defaults.

UnionDiscriminatorChanged

A union's discriminator field changed. Breaking — the on-wire format for the union slot shifts.

UnionMemberAdded

A member structured type was added to a union. Additive — a new option; existing blobs are unaffected.

UnionMemberRemoved

A member structured type was removed from a union. Breaking — blobs carrying that discriminator value fail.

UnionRegistry

Built-in + customer-supplied abstract-type → concrete-subtype mappings (Gradient → LinearGradient, …).

UnionRegistryEntry

One entry in a UnionRegistry, describing an abstract type and its known concrete subtypes.

UnionResolution

The product of resolving one abstract base into a discriminated union.

UpdateTokenWireIdEvent

Event that updates mutable design-token payload.

VariantArgumentsChanged

A factory variant's argument shape changed — its sourceKind or arg-to-field argMappings differ. Breaking — the decoder semantics for the variant shift.

WidgetChildrenSlotChanged

A widget's childrenSlot changed (none ↔ single ↔ list). Breaking — a structural blob change is required.

WireIdAllocationCandidate

A source/catalog entry that needs a wire ID allocation.

WireIdAllocator

Monotonic per-library wire-ID allocator.

WireIdCurrentState

Per-library materialized view derived from a wire-ID event log.

WireIdEntryState

Materialized current-state entry produced by replay.

WireIdEvent

Base type for all wire-ID event-log records.

WireIdEventField<T>

Optional event field that preserves JSON field presence.

WireIdReplayBuilder

Incremental builder for wire-ID current-state replay.

Enums

CompatClassification

The four-way compatibility classification for a catalog change.

DiagnosticSeverity

Severity values for internal compiler diagnostics.

RequiredFlagDirection

Direction of a required-flag flip on a property or structured field.

StructuredKind

Three-way verdict for classifyStructured.

WireIdEventKind

One of the append-only wire-ID event verbs.

Constants

abstractTypeAwaitingUnion → const IssueCode

Structured-type walk reached an abstract base type.

kBuiltInCategoryHeuristics → const List<CategoryRule>

Built-in category heuristics seeding the obvious cases. Patterns are anchored regex source strings; the consumer compiles them at filter time.

kBuiltInThemeBindingSeeds → const Map<String, ThemeBindingPath>

Initial closed set of (widget, property) → ThemeBindingPath seeds. Key shape: 'WidgetName.propertyName'.

kBuiltInWireIdBackfillActor → const String

Actor recorded on the initial built-in catalog backfill events.

kBuiltInWireIdBackfillTimestamp → const String

Timestamp recorded on the initial built-in catalog backfill events.

knownRecipeStructuredTypes → const Set<String>

Structured value types the recipe path decomposes natively. A field or parameter of one of these resolves to a StructuredShape whose structuredRef points at the type's own catalog entry.

restageLibraryForeignWidget → const IssueCode

A walked @RestageWidget class originates outside the declared package.

restageLibraryMalformed → const IssueCode

The @RestageLibrary annotation could not be const-evaluated, or is missing its required library field.

restageLibraryReservedNamespace → const IssueCode

@RestageLibrary declares a built-in Restage namespace as its own library.

restageLibraryUnexportedWidget → const IssueCode

An @RestageWidget class is reachable through a library in the @RestageLibrary barrel's export closure, but is not itself exposed by the barrel's export namespace (a show/hide clause excludes it).

structuredCycle → const IssueCode

Structured-type walk encountered a repeated type while recursing.

structuredDepthExceeded → const IssueCode

Structured-type walk exceeded its configured recursion depth.

structuredFactoryUnsupportedParam → const IssueCode

Structured factory variant has an unsupported parameter type.

unionMemberInvalid → const IssueCode

A union member resolved to a class element that is not a valid concrete subtype of the union's abstract base.

unionMemberUnresolved → const IssueCode

A union member named in the registry did not resolve to a class element.

Functions

abstractStructuredFallback(DartType type) → PropertyType?

Maps an abstract Flutter base type (e.g. Gradient, BoxBorder) to the legacy PropertyType member that downstream code uses to lower it on the wire.

appendWireIdEventsSync(File file, Iterable<WireIdEvent> events) → void

Appends canonical event lines to an existing log.

backfillRestageCatalogWireIds({required Catalog catalog, required WidgetLibrary library, Iterable<WireIdEvent> existingEvents = const [], String at = kBuiltInWireIdBackfillTimestamp, String by = kBuiltInWireIdBackfillActor}) → List<WireIdEvent>

Allocates the initial built-in wire-ID backfill for catalog.

catalogDeprecationFor(WireId id, List<WireIdEvent> events) → CatalogDeprecationInfo?

Returns the catalog-lifecycle deprecation for id by scanning events for DeprecateWireIdEvents that target id, or null when none exist.

classElementFor(DartType type) → ClassElement?

The ClassElement backing type, or null when type is not an interface type with a resolvable class element.

classifyCatalogChange(CatalogChange change) → CompatClassification

Classifies a detected CatalogChange per the compatibility taxonomy.

classifyStructured(DartType type, PolicyLedger policy) → StructuredKind

Classifies type against the structured-walk policy in policy.

computeCatalogDiff(Catalog baseline, Catalog current, {String? fromVersion, String? toVersion}) → CatalogDiffReport

Diffs two canonical catalog versions end to end: detects every per-entry change, classifies each per the compatibility taxonomy, and emits the CompatRules for the forwarding / breaking ones.

crossRefIndexForStructured(StructuredIR ir) → CrossRefResolutionIndex

Builds the cross-reference index for one structured type IR entry.

crossRefIndexForUnion(UnionIR ir) → CrossRefResolutionIndex

Unions resolve from lowered member source types, so they add no index data.

diffCatalogs(Catalog baseline, Catalog current) → List<CatalogChange>

Detects every per-entry change between two canonical catalog versions.

elementFqn(ClassElement element) → String

Fully-qualified-name helpers for analyzer elements.

emitCompatRules(List<CatalogChange> changes, {required String fromVersion, required String toVersion}) → List<CompatRule>

Emits a CompatRule for every forwarding and breaking change in changes, in input order.

encodeWireIdCurrentStateJson(WireIdCurrentState state) → String

Encodes a current-state snapshot as pretty deterministic JSON.

encodeWireIdEventJson(WireIdEvent event) → String

Returns a deterministic JSON string for a single event.

encodeWireIdEventsJsonl(Iterable<WireIdEvent> events) → String

Encodes events as canonical JSONL with LF line endings.

inferPropertyCategory(String name, CategoryHeuristics heuristics, {String? typeName}) → PropertyCategory?

Returns the PropertyCategory for a property named name, or null if no rule in heuristics matches.

inferPropertyPriority({required bool required, required PriorityHeuristics heuristics}) → PropertyPriority?

Returns the PropertyPriority for a property, or null if no priority claim can be made with confidence.

interfaceFqn(InterfaceElement element) → String

The <library-identifier>#<ClassName> identity for element.

interfaceFqnOrNull(InterfaceElement element) → String?

The <library-identifier>#<ClassName> identity for element, or null when the element has no name.

linkCrossReferences(Catalog catalog, CrossRefResolutionIndex index) → Catalog

Applies allocated wire IDs to post-allocation cross-reference sites.

literalFromDartObject(DartObject value) → Object?

Classifies a DartObject into a catalog-bakeable literal, or null when the value is not a supported literal shape. Mirrors the reflector's _decodePrimitive classification so the projected defaultValue stays byte-identical across the two default-resolution paths.

lowerStructured(StructuredIR ir) → StructuredEntry

Lowers one structured type IR entry to the public schema.

lowerUnion(UnionIR ir) → UnionEntry

Lowers one union IR entry to the public schema.

parseWireIdEventsJsonl(String contents, {String sourceDescription = 'wire_ids.events.jsonl'}) → List<WireIdEvent>

Parses wire_ids.events.jsonl contents.

readWireIdEventLogSync(File file) → List<WireIdEvent>

Reads a wire-ID event log from disk using strict UTF-8.

replayWireIdEvents({required String library, required Iterable<WireIdEvent> events, String? generatedAt, Map<String, WireIdCurrentState> externalStates = const {}}) → WireIdCurrentState

Replays one library's event stream into a materialized current state.

resolveDefaultFromConstant({required bool hasDefault, required DartObject? value}) → DefaultValueSource?

Resolves a parameter's pre-computed constant default into a DefaultValueSource, following the catalog output rule. Returns null when the catalog makes no claim about the default.

resolveParameterDefault(FormalParameterElement param, {required PropertyType targetType}) → DefaultValueSource?

Resolves the default of a constructor parameter into a DefaultValueSource, per the catalog output rule. This is the element-facing entry point the reflector calls — it holds the live FormalParameterElement and so can recover identifier names that a bare DartObject cannot (true enum members, class static-consts).

resolveThemeBindingDefault({required String widgetName, required String propertyName, required ThemeBindingSeeds seeds}) → ThemeBindingDefault?

Resolves a theme-binding default for widgetName.propertyName by looking the pair up in the policy's seeds table. Returns null when no seed matches. This is deterministic table application — not analyzer source inference; the seed table is a hand-maintained policy artifact.

resolveUnion({required ClassElement abstractElement, required WidgetLibrary library, required PolicyLedger policy, required String location, required MemberElementResolver resolveMember}) → UnionResolution?

Resolves abstractElement into a UnionResolution when its FQN is a registered abstract base in policy's union registry; returns null for an unregistered type (the caller keeps its existing fallback).

resolveValueShape(DartType type, {WidgetLibrary? library, PolicyLedger? policy, Set<String>? referencedUnionFqns}) → CatalogValueShape?

Resolves the semantic CatalogValueShape of a Dart type.

staticConstMemberName(DartObject value) → String?

Returns the name of the static-const field on value's declaring class whose constant value structurally equals value, or null when value is not a class-typed value or no field matches.

typeFqn(DartType type) → String?

The <library-identifier>#<ClassName> identity for type, or null when type is not an interface type with a resolvable ClassElement.

valueShapeNeedsLinking(CatalogValueShape? shape) → bool

Whether shape carries a reference that a later linking pass must resolve.

variantIdentity(FactoryVariant variant) → String

Stable plain-data identity for a lowered factory variant.

variantIdentityIr(FactoryVariantIR variant) → String

Stable plain-data identity for a factory variant IR entry.

walkRestageLibrary({required LibraryElement barrel, required AssetId barrelAssetId}) → LibraryWalkResult

Walks barrel for an @RestageLibrary declaration and enumerates the @RestageWidget-annotated classes exposed by its export namespace.

walkStructuredType({required ClassElement element, required WidgetLibrary library, required PolicyLedger policy, required String location, required Set<String> visited, required int depth}) → StructuredWalkResult

Walks a structured value type and returns its compiler IR.

wireIdEventFromJson(Map<String, Object?> json, {int? lineNumber}) → WireIdEvent

Parses one wire-ID event from its JSON object representation.

wireIdEventRefFromJson(Object? raw, {int? lineNumber}) → WireIdRef

Parses an event reference tuple from JSON.

wireIdEventRefToJson(WireIdRef ref) → Map<String, Object?>

Converts an event reference tuple to JSON.

wireIdKindFromEventType(String value) → WireIdKind

Parses an event-log type string.

wireIdKindToEventType(WireIdKind kind) → String

Converts a schema wire-ID kind to the event-log type string.

writeWireIdCurrentStateSync(File file, WireIdCurrentState state) → void

Writes a derived wire_ids.current.json file.

writeWireIdEventLogSync(File file, Iterable<WireIdEvent> events) → void

Writes a complete canonical wire-ID event log to disk.

Typedefs

MemberElementResolver = ClassElement? Function(String memberFqn)

Resolves a member FQN to its analyzer class element, or null when the member cannot be located in the resolved element graph.

RestageCatalogDeprecationResolver = DeprecationInfo? Function(WireId resolvedId, DeprecationInfo? existing)

Merges or replaces the deprecation on a catalog entry.

RestageDecompositionResolver = DecompositionRecipe Function(WidgetEntry widget, DecompositionRecipe recipe)

Resolves decomposition wire-ID references for the catalog-gen adapter.

RestagePropertyWireIdResolver = WireId Function(WidgetEntry widget, PropertyEntry property)

Resolves property wire IDs for the catalog-gen adapter.

RestageStructuredResolver = StructuredEntry Function(StructuredEntry entry)

Resolves structured entry wire identity for the catalog-gen adapter.

RestageUnionResolver = UnionEntry Function(UnionEntry entry)

Resolves union entry wire identity for the catalog-gen adapter.

RestageWidgetWireIdResolver = WireId Function(WidgetEntry widget)

Resolves widget wire IDs for the catalog-gen adapter.

Exceptions / Errors

CrossRefIndexException

Thrown when CrossRefResolutionIndex.merge hits a duplicate key whose targets differ — the upstream capture produced conflicting cross-reference resolution data for one site.

CrossRefLinkException

Thrown when a cross-reference cannot be resolved from the supplied index.

WireIdEventException

Error thrown when a wire-ID event is structurally invalid.

WireIdReplayException

Error thrown when event replay violates wire-ID invariants.