struct2ui 0.1.0__py3-none-any.whl

struct2ui/schema.py

@@ -0,0 +1,1118 @@
+"""Schema layer: parse cfg_t/*.json into a typed tree of Field nodes.
+
+Pure data, no Qt. Single responsibility: turn JSON files into an in-memory
+schema that the UI layer can render without re-walking JSON.
+
+Field hierarchy:
+    Field                   (abstract base; common metadata)
+    +-- ScalarField         (bool / int / float / str)
+    +-- EnumField           (named items dict)
+    +-- StructField         (ordered list of children Fields)
+    +-- ArrayField          (count + element-Field; element can be any Field)
+
+Design notes:
+- Resolution is eager: when we build the schema for a top-level type, we
+  follow nested struct/enum/array references *now*, so the renderer never
+  needs to know about cfg_t directories or files.
+- Cycles are guarded by a stack of currently-resolving type names.
+- Optional metadata (min/max/step/unit/tip/when/widget/render/value) are passed
+  through verbatim. We do not enforce them here.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+OPTIONAL_KEYS = ('widget', 'render', 'min', 'max', 'step', 'unit', 'tip', 'when')
+
+
+# --------------------------------------------------------------------------- #
+# Keyword vocabulary
+# --------------------------------------------------------------------------- #
+# Keys recognized inside a struct's `items` field-spec dict. Anything outside
+# this set in that position triggers an unknown-keyword error. Top-level dicts
+# in cfg_t/*.json are NOT checked here, because their keys are user-defined
+# type/const names interleaved with reserved keys like `typedefs`.
+
+FIELD_SPEC_KEYWORDS = frozenset({
+    'name', 'type', 'value', 'count',
+    'widget', 'render', 'min', 'max', 'step', 'unit', 'tip', 'when',
+})
+
+# Keys recognized inside a top-level type-definition block, keyed by the
+# block's own `type` value. e.g. a struct block may carry `type` + `items`,
+# an enum block may carry `type` + `items`. Unknown keys at this level
+# trigger an error.
+BLOCK_KEYWORDS_BY_TYPE: Dict[str, frozenset] = {
+    'struct': frozenset({'type', 'items'}),
+    'enum':   frozenset({'type', 'items'}),
+}
+
+# Keys allowed but ignored at any level (free-form metadata for humans).
+IGNORED_KEYWORDS = frozenset({
+    'version', 'description', 'author', 'comment', 'note',
+})
+
+# Reserved top-level keys with special meaning (not user types).
+TOP_LEVEL_RESERVED = frozenset({
+    'typedefs', 'flow',
+}) | IGNORED_KEYWORDS
+
+
+# --------------------------------------------------------------------------- #
+# Load report
+# --------------------------------------------------------------------------- #
+
+@dataclass
+class LoadIssue:
+    severity: str           # 'error' | 'warning'
+    file: str               # readable file path or label
+    path: str               # readable JSON path, e.g. 'a_cfg_t -> items[1]'
+    message: str
+    suggestion: Optional[str] = None  # e.g. "Did you mean 'tip'?"
+
+
+class LoadReport:
+    """Collects errors and warnings from JSON loading and validation."""
+
+    def __init__(self) -> None:
+        self.errors: List[LoadIssue] = []
+        self.warnings: List[LoadIssue] = []
+
+    def error(self, file: str, path: str, message: str,
+              suggestion: Optional[str] = None) -> None:
+        self.errors.append(LoadIssue('error', file, path, message, suggestion))
+
+    def warning(self, file: str, path: str, message: str,
+                suggestion: Optional[str] = None) -> None:
+        self.warnings.append(LoadIssue('warning', file, path, message, suggestion))
+
+    @property
+    def has_errors(self) -> bool:
+        return bool(self.errors)
+
+    @property
+    def has_warnings(self) -> bool:
+        return bool(self.warnings)
+
+    def extend(self, other: 'LoadReport') -> None:
+        """Merge another report's issues into this one (in order)."""
+        self.errors.extend(other.errors)
+        self.warnings.extend(other.warnings)
+
+    def format(self) -> str:
+        if not self.errors and not self.warnings:
+            return '=== Configuration Load Report ===\n[OK] no issues\n'
+        lines: List[str] = ['=== Configuration Load Report ===']
+        if self.errors:
+            lines.append(f'[Errors: {len(self.errors)}]')
+            for i, it in enumerate(self.errors, 1):
+                lines.extend(self._format_issue(i, it))
+        if self.warnings:
+            lines.append(f'[Warnings: {len(self.warnings)}]')
+            for i, it in enumerate(self.warnings, 1):
+                lines.extend(self._format_issue(i, it))
+        return '\n'.join(lines) + '\n'
+
+    @staticmethod
+    def _format_issue(idx: int, it: LoadIssue) -> List[str]:
+        out = [f'  [{idx}] {it.file}']
+        if it.path:
+            out.append(f'      at {it.path}')
+        out.append(f'      {it.message}')
+        if it.suggestion:
+            out.append(f'      {it.suggestion}')
+        return out
+
+
+def _suggest_keyword(unknown: str, vocabulary) -> Optional[str]:
+    """Return a 'Did you mean X?' hint if a close match exists, else None."""
+    matches = difflib.get_close_matches(unknown, list(vocabulary), n=1, cutoff=0.6)
+    if matches:
+        return f"Did you mean '{matches[0]}'?"
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# Field hierarchy
+# --------------------------------------------------------------------------- #
+
+@dataclass
+class Field:
+    name: str
+    c_type: str
+    default: Any = None
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def kind(self) -> str:
+        return type(self).__name__
+
+
+@dataclass
+class ScalarField(Field):
+    # ui_type in {'bool', 'int', 'float', 'str'}
+    ui_type: str = 'str'
+
+
+@dataclass
+class EnumField(Field):
+    items: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class StructField(Field):
+    children: List[Field] = field(default_factory=list)
+
+
+@dataclass
+class ArrayField(Field):
+    count: int = 0
+    element: Optional[Field] = None  # the field describing one element
+
+
+def array_dims_suffix(f: 'ArrayField') -> str:
+    """Bracketed dimensions for an array field's label/declaration.
+
+    Multi-dim arrays carry their original dims in meta['shape']; render them
+    as [a][b]... so a flat 1D storage of 12 still shows as [3][4]. Falls back
+    to the flat [count] when no shape metadata is present.
+    """
+    shape = f.meta.get('shape')
+    if isinstance(shape, (list, tuple)) and shape:
+        return ''.join(f'[{int(d)}]' for d in shape)
+    return f'[{f.count}]'
+
+
+# --------------------------------------------------------------------------- #
+# SchemaRegistry: loads cfg_t directory and builds Field trees on demand
+# --------------------------------------------------------------------------- #
+
+class SchemaRegistry:
+    """Loads all *.json files under cfg_dir and resolves type references.
+
+    Usage:
+        reg = SchemaRegistry('cfg_t')
+        root = reg.build('a_cfg_t')  # -> StructField
+    """
+
+    def __init__(self, cfg_dir: str):
+        self.cfg_dir = cfg_dir
+        self._raw_files: Dict[str, Dict[str, Any]] = {}    # base -> file json
+        self._enum_owner: Dict[str, str] = {}              # enum name -> file base
+        self._struct_owner: Dict[str, str] = {}            # struct name -> file base
+        self._alias: Dict[str, str] = {}                   # file base -> actual struct name (legacy)
+        self._consts: Dict[str, Any] = {}                  # global int/float consts
+        self._typedefs: Dict[str, str] = {}                # typedef alias -> base C type
+        self.report: LoadReport = LoadReport()
+        self._load_all()
+        # Step 3 (S1/S2/S4): semantic checks on declared min/max/step/count
+        # in cfg_t. These read raw JSON directly so all known structs are
+        # covered (lazy build only visits structs actually referenced from
+        # abc.json). S3 (instance value vs declared range) lives in
+        # FlowValidator._check_scalar where the value is in scope.
+        self._audit_semantics()
+
+    # ---- raw file loading ------------------------------------------------ #
+    def _load_all(self) -> None:
+        if not os.path.isdir(self.cfg_dir):
+            return
+        for fn in sorted(os.listdir(self.cfg_dir)):
+            if not fn.endswith('.json'):
+                continue
+            base = fn[:-5]
+            file_label = os.path.join(self.cfg_dir, fn)
+            try:
+                with open(file_label, 'r', encoding='utf-8') as f:
+                    data = json.load(f)
+            except json.JSONDecodeError as e:
+                self.report.error(file_label, '',
+                                  f'JSON parse error: {e.msg} (line {e.lineno}, col {e.colno})')
+                continue
+            except OSError as e:
+                self.report.error(file_label, '', f'cannot read file: {e}')
+                continue
+            if not isinstance(data, dict):
+                self.report.error(file_label, '',
+                                  f'top-level must be an object, got {type(data).__name__}')
+                continue
+            self._raw_files[base] = data
+            self._scan_keywords(file_label, data)
+            self._index_file(base, data)
+
+    def _index_file(self, base: str, data: Dict[str, Any]) -> None:
+        """Populate _enum_owner / _struct_owner / _consts / _alias from one file.
+
+        Aliasing rule: if the file's basename does not itself name a struct
+        (e.g. file `iir_cfg_t.json` defines struct `IIR_CFG_T`), point the
+        basename at the file's first struct so callers can refer to either
+        the basename or the actual struct name.
+        """
+        first_struct: Optional[str] = None
+        for k, v in data.items():
+            if k == 'typedefs' and isinstance(v, dict):
+                for alias, target in v.items():
+                    if isinstance(alias, str) and isinstance(target, str):
+                        self._typedefs.setdefault(alias, target)
+                continue
+            if isinstance(v, dict):
+                t = v.get('type')
+                if t == 'enum':
+                    self._enum_owner.setdefault(k, base)
+                elif t == 'struct':
+                    self._struct_owner.setdefault(k, base)
+                    if first_struct is None:
+                        first_struct = k
+            elif isinstance(v, (int, float)):
+                self._consts.setdefault(k, v)
+
+        if base not in self._struct_owner and first_struct is not None:
+            self._struct_owner[base] = base
+            self._alias[base] = first_struct
+
+    # ---- keyword scanning ----------------------------------------------- #
+    def _scan_keywords(self, file_label: str, data: Dict[str, Any]) -> None:
+        """Walk one cfg_t file and report unknown keywords.
+
+        Two layers are checked:
+          1. Block-level keys inside each top-level type-definition dict
+             (struct / enum). E.g. `items` mistyped as `i2tems`.
+          2. Field-spec keys inside a struct's `items` list entries.
+             E.g. `tip` mistyped as `tlp`.
+
+        Top-level dict keys themselves are NOT checked, because they are
+        user-defined type/const names mixed with reserved keys like
+        `typedefs`. Enum item dicts are NOT checked, because their keys
+        are user-defined enumerator names.
+        """
+        for top_key, top_val in data.items():
+            if not isinstance(top_val, dict):
+                continue
+            if top_key in TOP_LEVEL_RESERVED:
+                continue
+            block_type = top_val.get('type')
+            allowed = BLOCK_KEYWORDS_BY_TYPE.get(block_type)
+            if allowed is None:
+                # The block looks like a type definition (dict under a
+                # user-named top-level key) but lacks a recognizable `type`.
+                # Most likely `type` itself is mistyped, or the block-type
+                # value is unknown. Report and still try to scan for other
+                # problems (e.g. `items` mistyped) using a permissive
+                # whitelist so users see all issues at once.
+                type_lookalike = self._report_bad_block_type(
+                    file_label, top_key, top_val)
+                permissive = (frozenset({'type'})
+                              | BLOCK_KEYWORDS_BY_TYPE['struct']
+                              | BLOCK_KEYWORDS_BY_TYPE['enum'])
+                self._check_block_keys(file_label, top_key, top_val,
+                                       permissive,
+                                       skip_keys={type_lookalike} if type_lookalike else None,
+                                       label='malformed')
+                # In a malformed block we cannot trust block['items'].
+                # Scan every list-valued sub-key as a candidate items list,
+                # so typos like `items2` still get their field specs checked.
+                for sub_key, sub_val in top_val.items():
+                    if isinstance(sub_val, list):
+                        self._scan_field_specs(file_label, top_key, sub_key,
+                                               sub_val)
+                continue
+            self._check_block_keys(file_label, top_key, top_val, allowed,
+                                   label=block_type)
+            if block_type == 'struct':
+                self._check_struct_items(file_label, top_key, top_val)
+
+    def _report_bad_block_type(self, file_label: str, top_key: str,
+                               block: Dict[str, Any]) -> Optional[str]:
+        """Report a malformed type-definition block.
+
+        Returns the key (if any) that was identified as a `type` lookalike,
+        so the caller can avoid reporting it twice in the keyword scan.
+        """
+        if 'type' not in block:
+            matches = difflib.get_close_matches(
+                'type',
+                [k for k in block.keys() if isinstance(k, str)],
+                n=1, cutoff=0.6)
+            lookalike = matches[0] if matches else None
+            if lookalike:
+                hint = f"Found similar key {lookalike!r}; did you mean 'type'?"
+            else:
+                hint = "Add a 'type' key like \"type\":\"struct\" or \"type\":\"enum\"."
+            self.report.error(
+                file_label,
+                top_key,
+                "type-definition block missing 'type' key",
+                hint,
+            )
+            return lookalike
+        bad_value = block.get('type')
+        known = sorted(BLOCK_KEYWORDS_BY_TYPE.keys())
+        suggestion = None
+        if isinstance(bad_value, str):
+            suggestion = _suggest_keyword(bad_value, known)
+        if suggestion is None:
+            suggestion = f"Expected one of: {', '.join(known)}."
+        self.report.error(
+            file_label,
+            f'{top_key} -> type',
+            f"unknown block type {bad_value!r}",
+            suggestion,
+        )
+        return None
+
+    def _check_block_keys(self, file_label: str, top_key: str,
+                          block: Dict[str, Any], allowed: frozenset,
+                          skip_keys: Optional[set] = None,
+                          label: Optional[str] = None) -> None:
+        block_label = label or block.get('type') or 'block'
+        for k in block.keys():
+            if not isinstance(k, str):
+                continue
+            if k in allowed or k in IGNORED_KEYWORDS:
+                continue
+            if skip_keys and k in skip_keys:
+                continue
+            suggestion = _suggest_keyword(k, allowed | IGNORED_KEYWORDS)
+            self.report.error(
+                file_label,
+                f'{top_key} -> {k}',
+                f"unknown keyword '{k}' in {block_label} block",
+                suggestion,
+            )
+
+    def _check_struct_items(self, file_label: str, top_key: str,
+                            block: Dict[str, Any]) -> None:
+        items = block.get('items')
+        if items is None:
+            self.report.error(
+                file_label,
+                f'{top_key} -> items',
+                "struct block is missing 'items' list",
+            )
+            return
+        if not isinstance(items, list):
+            self.report.error(
+                file_label,
+                f'{top_key} -> items',
+                f"struct 'items' must be a list, got {type(items).__name__}",
+            )
+            return
+        self._scan_field_specs(file_label, top_key, 'items', items)
+
+    def _scan_field_specs(self, file_label: str, top_key: str,
+                          list_key: str, items: List[Any]) -> None:
+        """Validate keys inside each entry of a (suspected) items list.
+
+        `list_key` is the actual JSON key the list lives under, which may
+        be the canonical 'items' or a typo like 'items2'. Either way, the
+        list entries should be field-spec dicts and their keys are checked
+        against FIELD_SPEC_KEYWORDS.
+        """
+        for idx, spec in enumerate(items):
+            path_prefix = f'{top_key} -> {list_key}[{idx}]'
+            if not isinstance(spec, dict):
+                self.report.error(
+                    file_label,
+                    path_prefix,
+                    f"field spec must be an object, got {type(spec).__name__}",
+                )
+                continue
+            for k in spec.keys():
+                if not isinstance(k, str):
+                    continue
+                if k in FIELD_SPEC_KEYWORDS or k in IGNORED_KEYWORDS:
+                    continue
+                suggestion = _suggest_keyword(
+                    k, FIELD_SPEC_KEYWORDS | IGNORED_KEYWORDS)
+                self.report.error(
+                    file_label,
+                    f'{path_prefix} -> {k}',
+                    f"unknown keyword '{k}' in field spec",
+                    suggestion,
+                )
+
+    # ---- semantic audit (Step 3: S1 / S2 / S4) -------------------------- #
+    def _audit_semantics(self) -> None:
+        """Walk every cfg_t file's raw JSON and check declared semantics.
+
+        S1: min <= max when both are present
+        S2: step > 0 when present
+        S4: count > 0 (every dim, when count is a list)
+        """
+        for base, data in self._raw_files.items():
+            file_label = os.path.join(self.cfg_dir, base + '.json')
+            for top_key, top_val in data.items():
+                if (not isinstance(top_val, dict)
+                        or top_val.get('type') != 'struct'):
+                    continue
+                items = top_val.get('items')
+                if not isinstance(items, list):
+                    continue
+                for idx, spec in enumerate(items):
+                    if not isinstance(spec, dict):
+                        continue
+                    fname = spec.get('name') or f'<item {idx}>'
+                    path = f'{top_key} -> {fname}'
+                    self._audit_field_spec(file_label, path, spec)
+
+    def _audit_field_spec(self, file_label: str, path: str,
+                          spec: Dict[str, Any]) -> None:
+        # S4: count > 0 (per dim)
+        if 'count' in spec:
+            for dim in self._iter_count_dims(spec.get('count')):
+                resolved = self._safe_resolve_const(dim)
+                if resolved is None:
+                    continue
+                if resolved <= 0:
+                    self.report.error(
+                        file_label, f'{path} -> count',
+                        f"array count must be > 0, got {resolved}")
+
+        # S1 / S2 only apply to numeric fields. Use the field's ui_type
+        # (resolved through typedefs) to filter.
+        ftype = spec.get('type')
+        if not isinstance(ftype, str):
+            return
+        ui = _ctype_to_ui(self.resolve_alias(ftype))
+        if ui not in ('int', 'float'):
+            return
+
+        mn = spec.get('min')
+        mx = spec.get('max')
+        mn_num = mn if isinstance(mn, (int, float)) and not isinstance(mn, bool) else None
+        mx_num = mx if isinstance(mx, (int, float)) and not isinstance(mx, bool) else None
+
+        # S1: min <= max when both present and numeric.
+        if mn_num is not None and mx_num is not None and mn_num > mx_num:
+            self.report.error(
+                file_label, path,
+                f"min ({mn_num}) must be <= max ({mx_num})")
+
+        # S2: step > 0 when present and numeric.
+        if 'step' in spec:
+            st = spec.get('step')
+            if isinstance(st, bool) or not isinstance(st, (int, float)):
+                self.report.error(
+                    file_label, f'{path} -> step',
+                    f"step must be a number, got {type(st).__name__}")
+            elif st <= 0:
+                self.report.error(
+                    file_label, f'{path} -> step',
+                    f"step must be > 0, got {st}")
+
+    @staticmethod
+    def _iter_count_dims(raw_count: Any):
+        if isinstance(raw_count, (list, tuple)):
+            for d in raw_count:
+                yield d
+        else:
+            yield raw_count
+
+    def _safe_resolve_const(self, ref: Any) -> Optional[int]:
+        """Like resolve_const, but returns None on unresolvable input
+        instead of raising. Used by audits that want to skip silently
+        when a constant is unknown."""
+        if isinstance(ref, bool):
+            return None
+        if isinstance(ref, int):
+            return ref
+        if isinstance(ref, str) and ref in self._consts:
+            v = self._consts[ref]
+            return v if isinstance(v, int) else None
+        return None
+
+    # ---- public API ------------------------------------------------------ #
+    def has(self, type_name: str) -> bool:
+        return type_name in self._enum_owner or type_name in self._struct_owner
+
+    def is_enum(self, type_name: str) -> bool:
+        return type_name in self._enum_owner
+
+    def is_struct(self, type_name: str) -> bool:
+        return type_name in self._struct_owner
+
+    def known_struct_names(self) -> List[str]:
+        """All struct cfg type names known to this registry (sorted)."""
+        return sorted(self._struct_owner.keys())
+
+    def resolve_const(self, ref: Any) -> int:
+        if isinstance(ref, int):
+            return ref
+        if isinstance(ref, str) and ref in self._consts:
+            try:
+                return int(self._consts[ref])
+            except Exception:
+                return 0
+        try:
+            return int(ref)
+        except Exception:
+            return 0
+
+    def resolve_alias(self, type_name: str) -> str:
+        """Follow typedef alias chain to the base C type.
+
+        E.g. with `typedefs = {"gain_t":"int32_t"}`, resolve_alias("gain_t")
+        returns "int32_t". Non-aliases pass through unchanged. Cycles short-
+        circuit at the first repeat.
+        """
+        seen = set()
+        cur = type_name
+        while isinstance(cur, str) and cur in self._typedefs and cur not in seen:
+            seen.add(cur)
+            cur = self._typedefs[cur]
+        return cur
+
+    def get_enum_items(self, enum_name: str) -> Dict[str, Any]:
+        owner = self._enum_owner.get(enum_name)
+        if not owner:
+            return {}
+        return self._raw_files[owner].get(enum_name, {}).get('items', {}) or {}
+
+    def build(self, type_name: str) -> StructField:
+        """Build the full Field tree rooted at the given struct type."""
+        return self._build_struct(type_name, name=type_name, stack=[])
+
+    # ---- internal builders ---------------------------------------------- #
+    def _build_struct(self, type_name: str, name: str, stack: List[str]) -> StructField:
+        if type_name in stack:
+            # Cycle guard: emit empty struct rather than recursing forever.
+            return StructField(name=name, c_type=type_name, children=[])
+        owner = self._struct_owner.get(type_name)
+        if not owner:
+            return StructField(name=name, c_type=type_name, children=[])
+        # If type_name itself is a file basename aliased to an actual struct, follow it.
+        actual_name = self._alias.get(type_name, type_name)
+        struct_def = self._raw_files[owner].get(actual_name, {})
+        if not isinstance(struct_def, dict) or struct_def.get('type') != 'struct':
+            # Fallback: scan file for first struct (defensive).
+            for k, v in self._raw_files[owner].items():
+                if isinstance(v, dict) and v.get('type') == 'struct':
+                    struct_def = v
+                    break
+        items = struct_def.get('items', []) if isinstance(struct_def, dict) else []
+        children: List[Field] = []
+        new_stack = stack + [type_name]
+        for raw in items:
+            if not isinstance(raw, dict):
+                continue
+            child = self._build_field(raw, new_stack)
+            if child is not None:
+                children.append(child)
+        return StructField(name=name, c_type=type_name, children=children)
+
+    def _build_field(self, raw: Dict[str, Any], stack: List[str]) -> Optional[Field]:
+        fname = raw.get('name')
+        ftype = raw.get('type')
+        if not fname or not ftype:
+            return None
+        meta = {k: raw[k] for k in OPTIONAL_KEYS if k in raw}
+        default = raw.get('value')
+
+        # Resolve typedef alias on the way in (e.g. gain_t -> int32_t).
+        # We do this before any branch so 'count' + alias still works.
+        ftype = self.resolve_alias(ftype)
+
+        # Multi-dim count: count:[a, b] is treated as a flat 1D array of
+        # length a*b (matching the C ABI: float m[3][4] is 12 contiguous
+        # floats). meta.shape carries the original dims so the widget can
+        # render line-broken text for readability. Storage stays 1D.
+        raw_count = raw.get('count')
+        flat_n = None
+        shape = None
+        if isinstance(raw_count, (list, tuple)):
+            dims = [self.resolve_const(x) for x in raw_count]
+            flat_n = 1
+            for d in dims:
+                flat_n *= d
+            shape = dims
+
+        # char[N] is conventionally a C string, not a byte array.
+        # int8_t[N] keeps array semantics. The 'widget' meta can override either way.
+        # Multi-dim char (e.g. char[3][16]) does NOT collapse to a string -
+        # it stays a 1D array of (a*b) chars; keep it as plain array.
+        if ('count' in raw and ftype.lower() == 'char'
+                and 'widget' not in meta and shape is None):
+            n = self.resolve_const(raw_count)
+            if default is None:
+                default = ''
+            scalar_meta = dict(meta)
+            scalar_meta['maxlen'] = n
+            return ScalarField(name=fname, c_type=f'char[{n}]', default=default,
+                               meta=scalar_meta, ui_type='str')
+
+        # Array? -> ArrayField wrapping the element field
+        if 'count' in raw:
+            n = flat_n if shape is not None else self.resolve_const(raw_count)
+            elem_raw = {k: v for k, v in raw.items() if k != 'count'}
+            elem_raw['type'] = ftype
+            element = self._build_field(elem_raw, stack)
+            if element is None:
+                return None
+            arr_meta = dict(meta)
+            if shape is not None:
+                arr_meta['shape'] = shape
+            return ArrayField(name=fname, c_type=ftype, default=default,
+                              meta=arr_meta, count=n, element=element)
+
+        # Struct?
+        if self.is_struct(ftype):
+            sub = self._build_struct(ftype, name=fname, stack=stack)
+            sub.default = default
+            sub.meta = meta
+            return sub
+
+        # Enum?
+        if self.is_enum(ftype):
+            items = self.get_enum_items(ftype)
+            if default is None and items:
+                default = next(iter(items.keys()))
+            return EnumField(name=fname, c_type=ftype, default=default,
+                             meta=meta, items=items)
+
+        # Scalar
+        ui_type = _ctype_to_ui(ftype)
+        if default is None:
+            default = _ui_zero(ui_type)
+        return ScalarField(name=fname, c_type=ftype, default=default,
+                           meta=meta, ui_type=ui_type)
+
+
+# --------------------------------------------------------------------------- #
+# Type helpers
+# --------------------------------------------------------------------------- #
+
+def _ctype_to_ui(c_type: str) -> str:
+    ct = (c_type or '').lower()
+    if ct in ('bool', '_bool'):
+        return 'bool'
+    if ct.startswith(('int', 'uint')) or ct in ('size_t', 'long', 'short'):
+        return 'int'
+    if ct in ('float', 'double'):
+        return 'float'
+    return 'str'
+
+
+def _ui_zero(ui_type: str) -> Any:
+    if ui_type == 'bool':
+        return False
+    if ui_type == 'int':
+        return 0
+    if ui_type == 'float':
+        return 0.0
+    return ''
+
+
+# --------------------------------------------------------------------------- #
+# Instance values: merge user-provided dict into the schema tree
+# --------------------------------------------------------------------------- #
+
+def merge_instance(field_node: Field, provided: Any) -> Any:
+    """Return the effective value for `field_node`, merging `provided` over defaults.
+
+    - For ScalarField/EnumField: returns a scalar
+    - For StructField: returns a dict of child-name -> merged-value
+    - For ArrayField: returns a list of length count
+    """
+    if isinstance(field_node, ArrayField):
+        # widget=file: the array is represented as a single path string,
+        # not an expanded list. Pass the value through verbatim so the GUI
+        # can render the file widget.
+        if field_node.meta.get('widget') == 'file':
+            return provided if provided is not None else field_node.default
+        n = field_node.count
+        out = []
+        provided_list = provided if isinstance(provided, list) else []
+        for i in range(n):
+            elem = provided_list[i] if i < len(provided_list) else None
+            out.append(merge_instance(field_node.element, elem))
+        return out
+
+    if isinstance(field_node, StructField):
+        out = {}
+        prov = provided if isinstance(provided, dict) else {}
+        for ch in field_node.children:
+            out[ch.name] = merge_instance(ch, prov.get(ch.name))
+        return out
+
+    # scalar / enum
+    if provided is not None:
+        return provided
+    return field_node.default
+
+
+# --------------------------------------------------------------------------- #
+# Flow validator: cross-checks abc.json against a SchemaRegistry
+# --------------------------------------------------------------------------- #
+
+# abc.json structural keywords. Anything outside this set in a stage block
+# triggers an unknown-keyword error. (Values inside `items` are user data,
+# not keywords, and are handled by L2/L3/L4 instead.)
+STAGE_KEYWORDS = frozenset({'type', 'items'})
+
+# abc.json group-level keys that are reserved (not stage names).
+GROUP_RESERVED = frozenset({'Flow'}) | IGNORED_KEYWORDS
+
+
+class FlowValidator:
+    """Validate an abc.json flow file against a loaded SchemaRegistry.
+
+    Layers (collect-then-display, never stop on first error):
+      A  : structural keyword spelling in stage blocks (type / items)
+      A2 : Flow list shape
+      L1 : each stage.type names a struct cfg_t known to the registry
+      L2 : each items key is a real field of that struct
+      L3 : each items value is type-compatible with the field's c_type
+           (C-style coercion: bool<->int, int+0.0 ok, float<-int ok, etc.)
+      L4 : enum-typed values must be a known enumerator string
+      L5 : Flow listed stages must be defined; defined stages should appear
+           in Flow (warning if not, since orphan stages are recoverable)
+    """
+
+    def __init__(self, registry: 'SchemaRegistry', flow_file: str):
+        self.registry = registry
+        self.flow_file = flow_file
+        self.report = LoadReport()
+
+    # ---- entrypoint ----------------------------------------------------- #
+    def validate(self) -> LoadReport:
+        if not os.path.exists(self.flow_file):
+            self.report.error(self.flow_file, '', 'flow file not found')
+            return self.report
+        try:
+            with open(self.flow_file, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            self.report.error(
+                self.flow_file, '',
+                f'JSON parse error: {e.msg} (line {e.lineno}, col {e.colno})')
+            return self.report
+        except OSError as e:
+            self.report.error(self.flow_file, '', f'cannot read file: {e}')
+            return self.report
+        if not isinstance(data, dict):
+            self.report.error(
+                self.flow_file, '',
+                f'top-level must be an object, got {type(data).__name__}')
+            return self.report
+
+        for group_key, group in data.items():
+            if not isinstance(group, dict):
+                self.report.error(
+                    self.flow_file, group_key,
+                    f"group must be an object, got {type(group).__name__}")
+                continue
+            self._validate_group(group_key, group)
+        return self.report
+
+    # ---- group / Flow / stages ----------------------------------------- #
+    def _find_flow_lookalike(self, group: Dict[str, Any]) -> Optional[str]:
+        """Return a key in `group` that looks like a misspelled 'Flow'.
+
+        Match if either the lowercased form equals 'flow' (catches case
+        variants and small letter-order typos like 'flwo') or difflib's
+        ratio is high enough (catches inserted/dropped chars like 'F1low').
+        """
+        for k in group.keys():
+            if not isinstance(k, str) or k == 'Flow' or k in IGNORED_KEYWORDS:
+                continue
+            kl = k.lower()
+            if kl == 'flow' or difflib.get_close_matches(
+                    kl, ['flow'], n=1, cutoff=0.6):
+                return k
+        return None
+
+    def _validate_group(self, group_key: str, group: Dict[str, Any]) -> None:
+        # A2: Flow shape. flow_present marks whether we have a trustworthy
+        # Flow list to compare stages against; if not, suppress the
+        # "defined but not listed in Flow" warning entirely (it would
+        # otherwise fire for every stage and add noise on top of the real
+        # error).
+        flow_val = group.get('Flow')
+        flow_list: List[str]
+        flow_present: bool
+        if flow_val is None:
+            # Look for a near-miss key (e.g. 'F1low', 'flow', 'Flwo') so the
+            # user gets one actionable error instead of two unrelated ones.
+            misspelled = self._find_flow_lookalike(group)
+            if misspelled is not None:
+                self.report.error(
+                    self.flow_file, f'{group_key} -> {misspelled}',
+                    f"unknown key '{misspelled}'", "Did you mean 'Flow'?")
+            else:
+                self.report.error(self.flow_file, group_key,
+                                  "group is missing 'Flow' list")
+            flow_list = []
+            flow_present = False
+        elif not isinstance(flow_val, list):
+            self.report.error(
+                self.flow_file, f'{group_key} -> Flow',
+                f"Flow must be a list, got {type(flow_val).__name__}")
+            flow_list = []
+            flow_present = False
+        else:
+            flow_list = [s for s in flow_val if isinstance(s, str)]
+            flow_present = True
+
+        # Stage candidates: every key that is not a group-reserved key,
+        # excluding any 'Flow' look-alike already reported above (so it
+        # does not get re-flagged as a malformed stage).
+        misspelled_flow = None
+        if not flow_present and flow_val is None:
+            misspelled_flow = self._find_flow_lookalike(group)
+        stage_keys = [k for k in group.keys()
+                      if k not in GROUP_RESERVED and k != misspelled_flow]
+
+        # L5 - part 1: every stage in Flow must be defined.
+        for stage_name in flow_list:
+            if stage_name not in stage_keys:
+                self.report.error(
+                    self.flow_file,
+                    f'{group_key} -> Flow',
+                    f"Flow references stage '{stage_name}' but no such "
+                    f"stage block is defined")
+
+        # L5 - part 2: every defined stage should appear in Flow (warning).
+        # Skip when Flow is missing/malformed - the comparison baseline is
+        # untrustworthy and would only generate noise.
+        if flow_present:
+            flow_set = set(flow_list)
+            for stage_name in stage_keys:
+                if stage_name not in flow_set:
+                    self.report.warning(
+                        self.flow_file,
+                        f'{group_key} -> {stage_name}',
+                        f"stage '{stage_name}' is defined but not listed in Flow")
+
+        for stage_name in stage_keys:
+            stage = group[stage_name]
+            if not isinstance(stage, dict):
+                self.report.error(
+                    self.flow_file,
+                    f'{group_key} -> {stage_name}',
+                    f"stage must be an object, got {type(stage).__name__}")
+                continue
+            self._validate_stage(group_key, stage_name, stage)
+
+    def _validate_stage(self, group_key: str, stage_name: str,
+                        stage: Dict[str, Any]) -> None:
+        path = f'{group_key} -> {stage_name}'
+
+        # A: structural keyword spelling. Track which STAGE_KEYWORDS were
+        # misspelled so we can suppress redundant "missing 'type'/'items'"
+        # errors below - if 'typ1e' is already flagged as a typo for 'type',
+        # also reporting "missing 'type'" only adds noise.
+        misspelled_targets: set = set()
+        vocab = STAGE_KEYWORDS | IGNORED_KEYWORDS
+        vocab_list = list(vocab)
+        for k in stage.keys():
+            if not isinstance(k, str):
+                continue
+            if k in STAGE_KEYWORDS or k in IGNORED_KEYWORDS:
+                continue
+            matches = difflib.get_close_matches(k, vocab_list, n=1, cutoff=0.6)
+            suggestion = (f"Did you mean '{matches[0]}'?"
+                          if matches else None)
+            if matches and matches[0] in STAGE_KEYWORDS:
+                misspelled_targets.add(matches[0])
+            self.report.error(
+                self.flow_file,
+                f'{path} -> {k}',
+                f"unknown keyword '{k}' in stage block",
+                suggestion,
+            )
+
+        # L1: type must name a known struct cfg_t.
+        type_name = stage.get('type')
+        if type_name is None:
+            if 'type' not in misspelled_targets:
+                self.report.error(self.flow_file, path,
+                                  "stage is missing 'type'")
+            return
+        if not isinstance(type_name, str):
+            self.report.error(
+                self.flow_file, f'{path} -> type',
+                f"'type' must be a string, got {type(type_name).__name__}")
+            return
+        if not self.registry.has(type_name):
+            known = self.registry.known_struct_names()
+            suggestion = _suggest_keyword(type_name, known) if known else None
+            self.report.error(
+                self.flow_file, f'{path} -> type',
+                f"unknown cfg type '{type_name}'", suggestion)
+            return
+        if not self.registry.is_struct(type_name):
+            self.report.error(
+                self.flow_file, f'{path} -> type',
+                f"stage cfg type '{type_name}' must be a struct, not "
+                f"an enum")
+            return
+
+        # L2~L4: walk the schema tree.
+        provided = stage.get('items')
+        if provided is None:
+            if 'items' not in misspelled_targets:
+                self.report.error(self.flow_file, path,
+                                  "stage is missing 'items'")
+            return
+        if not isinstance(provided, dict):
+            self.report.error(
+                self.flow_file, f'{path} -> items',
+                f"'items' must be an object, got {type(provided).__name__}")
+            return
+        root = self.registry.build(type_name)
+        self._check_struct_values(path, root, provided)
+
+    # ---- value-vs-schema recursion -------------------------------------- #
+    def _check_struct_values(self, path: str, struct: 'StructField',
+                             provided: Dict[str, Any]) -> None:
+        children_by_name = {ch.name: ch for ch in struct.children}
+        for key, val in provided.items():
+            sub_path = f'{path} -> {key}'
+            child = children_by_name.get(key)
+            if child is None:
+                # L2
+                suggestion = _suggest_keyword(key, list(children_by_name))
+                self.report.error(
+                    self.flow_file, sub_path,
+                    f"unknown field '{key}' (cfg type {struct.c_type})",
+                    suggestion,
+                )
+                continue
+            self._check_field_value(sub_path, child, val)
+
+    def _check_field_value(self, path: str, field_node: 'Field',
+                           value: Any) -> None:
+        if isinstance(field_node, StructField):
+            if not isinstance(value, dict):
+                self.report.error(
+                    self.flow_file, path,
+                    f"expected object for struct field '{field_node.name}', "
+                    f"got {type(value).__name__}")
+                return
+            self._check_struct_values(path, field_node, value)
+            return
+        if isinstance(field_node, ArrayField):
+            # widget=file: array is represented as a single path string.
+            if field_node.meta.get('widget') == 'file':
+                if not isinstance(value, str):
+                    self.report.error(
+                        self.flow_file, path,
+                        f"expected file path string for '{field_node.name}', "
+                        f"got {type(value).__name__}")
+                return
+            if not isinstance(value, list):
+                self.report.error(
+                    self.flow_file, path,
+                    f"expected list for array field '{field_node.name}' "
+                    f"(count={field_node.count}), got {type(value).__name__}")
+                return
+            if len(value) != field_node.count:
+                self.report.warning(
+                    self.flow_file, path,
+                    f"array length {len(value)} does not match "
+                    f"declared count {field_node.count}")
+            for i, elem in enumerate(value):
+                self._check_field_value(f'{path}[{i}]',
+                                        field_node.element, elem)
+            return
+        if isinstance(field_node, EnumField):
+            # L4
+            if not isinstance(value, str):
+                self.report.error(
+                    self.flow_file, path,
+                    f"expected enumerator string for '{field_node.name}' "
+                    f"(enum {field_node.c_type}), got {type(value).__name__}")
+                return
+            if value not in field_node.items:
+                suggestion = _suggest_keyword(value, list(field_node.items))
+                self.report.error(
+                    self.flow_file, path,
+                    f"unknown enumerator '{value}' for enum "
+                    f"{field_node.c_type}", suggestion)
+            return
+        if isinstance(field_node, ScalarField):
+            self._check_scalar(path, field_node, value)
+
+    def _check_scalar(self, path: str, field_node: 'ScalarField',
+                      value: Any) -> None:
+        ui = field_node.ui_type
+        # bool: accepts bool or 0/1 ints. No range check (only two values).
+        if ui == 'bool':
+            if isinstance(value, bool):
+                return
+            if isinstance(value, int) and value in (0, 1):
+                return
+            self.report.error(
+                self.flow_file, path,
+                f"expected bool for '{field_node.name}' "
+                f"(c_type {field_node.c_type}), got "
+                f"{type(value).__name__}")
+            return
+        # int: accepts bool (treated as 0/1), int, or float with no
+        # fractional part. After type check passes, S3 range check runs.
+        if ui == 'int':
+            if isinstance(value, bool):
+                self._check_range(path, field_node, int(value))
+                return
+            if isinstance(value, int):
+                self._check_range(path, field_node, value)
+                return
+            if isinstance(value, float) and value.is_integer():
+                self._check_range(path, field_node, int(value))
+                return
+            self.report.error(
+                self.flow_file, path,
+                f"expected integer for '{field_node.name}' "
+                f"(c_type {field_node.c_type}), got "
+                f"{type(value).__name__}"
+                + (f" with fractional part {value!r}"
+                   if isinstance(value, float) else ''))
+            return
+        # float: accepts bool/int/float; S3 range check after type passes.
+        if ui == 'float':
+            if isinstance(value, bool):
+                self._check_range(path, field_node, float(int(value)))
+                return
+            if isinstance(value, (int, float)):
+                self._check_range(path, field_node, float(value))
+                return
+            self.report.error(
+                self.flow_file, path,
+                f"expected number for '{field_node.name}' "
+                f"(c_type {field_node.c_type}), got "
+                f"{type(value).__name__}")
+            return
+        # str / char[N]: accepts strings only.
+        if ui == 'str':
+            if isinstance(value, str):
+                return
+            self.report.error(
+                self.flow_file, path,
+                f"expected string for '{field_node.name}' "
+                f"(c_type {field_node.c_type}), got "
+                f"{type(value).__name__}")
+            return
+
+    def _check_range(self, path: str, field_node: 'ScalarField',
+                     value) -> None:
+        """S3: numeric value must fall in [min, max] when declared."""
+        meta = field_node.meta
+        mn = meta.get('min')
+        mx = meta.get('max')
+        mn_ok = isinstance(mn, (int, float)) and not isinstance(mn, bool)
+        mx_ok = isinstance(mx, (int, float)) and not isinstance(mx, bool)
+        if mn_ok and value < mn:
+            self.report.error(
+                self.flow_file, path,
+                f"value {value} is below declared min {mn}")
+            return
+        if mx_ok and value > mx:
+            self.report.error(
+                self.flow_file, path,
+                f"value {value} exceeds declared max {mx}")
+            return