baucli 1.0.1__py3-none-any.whl

baucli/apex_rebuild.py

@@ -0,0 +1,1458 @@
+"""APEX page rebuild — rewrite labels / alignment / format masks in .apx files
+from BAU table metadata, and optionally push the rewritten page back into
+the running APEX instance via `sql apex import`.
+
+Scope (matches the agreement with the user):
+    - Page items inside form regions:   `pageItem <NAME> ( ... )`
+    - IR/IG columns inside report regions:  `column <NAME> ( ... )`
+    - savedReport `displayColumn <NAME> ( ... )` — sequence reordering only.
+
+Attributes rewritten when a BAU match is found:
+    * `label: ...` on pageItem  →  BAU.LABEL
+    * `heading { heading: ... }` on column  →  BAU.LABEL
+    * `help { helpText: ... }` on pageItem  →  BAU.DESCRIPTION
+      (single-line collapsed; help is always the LAST nested block — the
+      dominant position across every sampled export)
+    * `settings { textCase: upper|lower }`  →  BAU.TEXT_CASE U/L
+      (textField blocks only; Initcap has no APEX equivalent and is skipped)
+    * `appearance { formatMask: ... }`  →  BAU.FORMAT_MASK (added if missing)
+    * `layout { columnAlignment: ... }`  →  BAU.ALIGN_REPORT or ALIGN_FORM
+      (mapped L/C/R  →  start/center/end; missing means "leave as-is")
+    * `type: hidden` when BAU.HIDDEN = Y — display-only properties
+      (formatMask, columnAlignment) are STRIPPED from blocks that are or
+      become hidden: the APEX 26 parser rejects them there (zero occurrences
+      inside `type: hidden` blocks across all sampled exports)
+    * `type: displayOnly` when BAU.READ_ONLY = Y and BAU.HIDDEN != Y (IR cols)
+    * `readOnly { type: always }` when BAU.READ_ONLY = Y (pageItem)
+
+Design choices
+==============
+The .apx format isn't well-described publicly, but it is a deterministic
+indented key/value grammar with balanced parentheses for blocks. A full
+parser would be overkill for ~10 attributes; instead the module:
+    1. Loads the file as text.
+    2. Scans for the markers `pageItem <NAME> (`, `column <NAME> (`,
+       `displayColumn <NAME> (`.
+    3. For each, walks forward to the matching `)` (paren-depth aware,
+       string-literal aware) to delimit the block.
+    4. Within the block, applies idempotent text edits — read the existing
+       value, decide on new value, splice the new text back into the buffer.
+
+The script never reorders blocks (would be too invasive without a proper
+parser). For column ordering, only `sequence:` inside layout/displayColumn
+is touched, leaving the textual block order alone.
+
+Discovery
+=========
+The .apx file is found via the project convention:
+    <project-root>/apex/<workspace>/pages/p<padded-id>-*.apx
+The function `find_apex_file` returns the unique match or raises with a
+diagnostic message listing what it tried.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Data carrier for the BAU metadata
+# ─────────────────────────────────────────────────────────────────────────────
+@dataclass
+class BauColumn:
+    name: str
+    label: str | None = None
+    description: str | None = None
+    format_mask: str | None = None
+    align_report: str | None = None  # 'L'|'C'|'R' or None
+    align_form: str | None = None
+    text_case: str | None = None
+    hidden: bool = False
+    read_only: bool = False
+    show_in_forms: bool = True
+    show_in_reports: bool = True
+    report_display_order: int | None = None
+    form_display_order: int | None = None
+    is_pk: bool = False
+    is_fk: bool = False
+    type: str | None = None
+    form_item_type: str | None = None  # exact APEXLang token (checkbox, ...)
+    # UI default for the generated item: form_default (explicit/rule, used
+    # as-is) takes precedence over the raw table data_default (filtered to
+    # literals by _safe_default).
+    form_default: str | None = None
+    data_default: str | None = None
+    # CHECK-constraint domain as (return_value, display_label) pairs — used
+    # to synthesize a static LOV when FORM_ITEM_TYPE needs one.
+    domain_values: list = field(default_factory=list)
+
+    @classmethod
+    def from_api(cls, d: dict) -> "BauColumn":
+        return cls(
+            name=d.get("name", "").upper(),
+            label=d.get("label"),
+            description=d.get("description"),
+            format_mask=d.get("format_mask"),
+            align_report=d.get("align_report"),
+            align_form=d.get("align_form"),
+            text_case=d.get("text_case"),
+            hidden=bool(d.get("hidden")),
+            read_only=bool(d.get("read_only")),
+            show_in_forms=d.get("show_in_forms") != False,
+            show_in_reports=d.get("show_in_reports") != False,
+            report_display_order=d.get("report_display_order"),
+            form_display_order=d.get("form_display_order"),
+            is_pk=bool(d.get("is_pk")),
+            is_fk=bool(d.get("is_fk")),
+            type=d.get("type"),
+            form_item_type=d.get("form_item_type"),
+            form_default=d.get("form_default"),
+            data_default=d.get("data_default"),
+            domain_values=[
+                (dv.get("value"), dv.get("label") or dv.get("value"))
+                for dv in (d.get("domain_values") or [])
+                if dv.get("value") is not None
+            ],
+        )
+
+
+# IR/IG `column` blocks use `layout { columnAlignment: start|center|end }`.
+ALIGN_MAP = {"L": "start", "C": "center", "R": "end"}
+# `pageItem` blocks use `layout { alignment: left|center|right }` — a
+# different key AND vocabulary (835 columnAlignment occurrences in the
+# sampled exports, all in columns; pageItems only ever carry `alignment`).
+ALIGN_MAP_ITEM = {"L": "left", "C": "center", "R": "right"}
+
+# BAU TEXT_CASE → APEXLang `settings { textCase: ... }` token. 'I' (Initcap)
+# has no APEX equivalent and is intentionally absent.
+TEXT_CASE_MAP = {"U": "upper", "L": "lower"}
+
+# Item types that legitimately carry an `lov { ... }` block. When
+# FORM_ITEM_TYPE retypes an item away from these, the leftover lov block
+# is invalid and must be stripped.
+LOV_ITEM_TYPES = {"selectList", "radioGroup", "popupLov", "shuttle",
+                  "checkboxGroup"}
+
+# Item types where `appearance { height: N }` (number of rows) is valid.
+# Every other type rejects it as INVALID_PROPERTY at import, so when a
+# FORM_ITEM_TYPE retype moves an item away from these the leftover height
+# must be stripped (e.g. a textField with height:1 retyped to radioGroup).
+HEIGHT_ITEM_TYPES = {"textarea", "richTextEditor", "markdownEditor"}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Auto-discovery of tables referenced by a page
+# ─────────────────────────────────────────────────────────────────────────────
+# Common SQL identifiers that are not table names but appear after FROM / JOIN
+# (subquery aliases, set-keywords, system pseudo-tables, CTE markers).
+_NOT_A_TABLE = {
+    "DUAL", "SELECT", "WHERE", "WITH", "ORDER", "GROUP",
+    "LATERAL", "TABLE", "VALUES", "UNION", "JOIN", "ON",
+}
+
+
+def discover_tables(source: str) -> list[str]:
+    """Return the uppercase table names referenced by a page, in priority
+    order.
+
+    Looks at two signals:
+
+    1. `tableName: X` lines — APEXLang's explicit table reference in form
+       regions and table-mode IRs.
+    2. `FROM <schema>.<table>` and `JOIN <schema>.<table>` inside `sqlQuery`
+       blocks (triple-backtick fences). The schema prefix is stripped.
+
+    ORDER MATTERS: `tableName:`-sourced tables come first (file order), then
+    FROM/JOIN-sourced ones. The caller aggregates column metadata first-wins,
+    so on column-name collisions (ID, ACTIVE and audit columns exist in
+    EVERY BAU-convention table) the form's base table takes precedence over
+    lookup/join tables.
+
+    SQL identifiers that occur after FROM/JOIN but aren't tables (DUAL,
+    subquery aliases, etc.) are filtered out by name. Anything not known to
+    BAU just returns empty `columns` and contributes nothing — so the cost
+    of a false positive here is one extra REST call.
+    """
+    ordered: list[str] = []
+    seen: set[str] = set()
+
+    def _add(name: str) -> None:
+        if name not in seen:
+            seen.add(name)
+            ordered.append(name)
+
+    for m in re.finditer(
+        r"^\s*tableName\s*:\s*([A-Za-z_][\w]*)", source, re.MULTILINE
+    ):
+        _add(m.group(1).upper())
+
+    for m in re.finditer(
+        r"\b(?:from|join)\s+(?:[A-Za-z_][\w]*\.)?([A-Za-z_][\w]*)",
+        source, re.IGNORECASE,
+    ):
+        name = m.group(1).upper()
+        if name in _NOT_A_TABLE:
+            continue
+        _add(name)
+
+    return ordered
+
+
+# Simple [schema.]table.column / column reference (the "this column IS the
+# stored value" case). Anything else aliased to a column name (scalar
+# subquery, function call, CASE, concat …) is a DERIVED display value.
+_BARE_COLREF = re.compile(
+    r'^"?[A-Za-z_][\w$#]*"?(?:\s*\.\s*"?[A-Za-z_][\w$#]*"?){0,2}$')
+# Split a select item into (expression, output-alias). Alias = trailing
+# identifier, with optional `AS`. Lazy head + `$` anchor force the alias to
+# be the LAST token even past CASE/END.
+_SELECT_ALIAS = re.compile(
+    r'^(.*?)\s+(?:as\s+)?"?([A-Za-z_][\w$#]*)"?$',
+    re.IGNORECASE | re.DOTALL)
+
+
+def derived_display_cols(source: str) -> set[str]:
+    """Return the UPPER output names of select-list projections that render a
+    DERIVED value (scalar subquery / function / expression) aliased to a
+    column name — e.g. `(select nome from … where id = t.SETOR_ID) SETOR_ID`.
+
+    Such columns display a STRING (the looked-up name), so the numeric-ID
+    metadata BAU holds for the underlying column (center align, 000000 mask)
+    must NOT be applied. Parsing is paren-aware so subquery commas/FROMs don't
+    break the split. Best-effort: on any oddity the column is simply omitted
+    (treated as non-derived), never raising."""
+    out: set[str] = set()
+    try:
+        for m in re.finditer(r"sqlQuery\s*:\s*```(?:sql)?\n(.*?)```",
+                             source, re.DOTALL | re.IGNORECASE):
+            sql = m.group(1)
+            # Isolate the top-level select list: after the first `select`,
+            # up to the matching top-level `from` (depth 0).
+            sm = re.search(r"\bselect\b", sql, re.IGNORECASE)
+            if not sm:
+                continue
+            i, depth, start = sm.end(), 0, sm.end()
+            list_end = None
+            while i < len(sql):
+                ch = sql[i]
+                if ch == "(":
+                    depth += 1
+                elif ch == ")":
+                    depth -= 1
+                elif depth == 0 and re.match(r"\bfrom\b", sql[i:], re.IGNORECASE):
+                    list_end = i
+                    break
+                i += 1
+            select_list = sql[start:list_end if list_end is not None else len(sql)]
+            # Paren-aware split on top-level commas.
+            items, depth, buf = [], 0, []
+            for ch in select_list:
+                if ch == "(":
+                    depth += 1
+                elif ch == ")":
+                    depth -= 1
+                if ch == "," and depth == 0:
+                    items.append("".join(buf)); buf = []
+                else:
+                    buf.append(ch)
+            if buf:
+                items.append("".join(buf))
+            for raw in items:
+                item = raw.strip()
+                if not item:
+                    continue
+                am = _SELECT_ALIAS.match(item)
+                if am:
+                    expr, alias = am.group(1).strip(), am.group(2)
+                else:
+                    expr, alias = item, item.split(".")[-1].strip('"')
+                if not _BARE_COLREF.match(expr):
+                    out.add(alias.upper())
+    except Exception:
+        return out
+    return out
+
+
+def bau_columns_differ(a: "BauColumn", b: "BauColumn") -> bool:
+    """True when two same-named columns (from different tables) would drive
+    different page edits — the signal for the cross-table collision warning
+    in the CLI. Identity fields (name, is_pk, is_fk, type) are ignored."""
+    keys = (
+        "label", "description", "format_mask", "align_report", "align_form",
+        "text_case", "hidden", "read_only",
+        "report_display_order", "form_display_order",
+    )
+    return any(getattr(a, k) != getattr(b, k) for k in keys)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SQLcl `apex import` driver
+# ─────────────────────────────────────────────────────────────────────────────
+DEFAULT_SQLCL = (
+    "$HOME/.vscode/extensions/oracle.sql-developer-26.1.2-darwin-arm64/"
+    "dbtools/sqlcl/bin/sql"
+)
+
+
+@dataclass
+class ImportResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        # SQLcl exits 0 on success. Errors that don't bubble to exit-code
+        # (like ORA-* inside the script, or APEXLang-level "workspace is
+        # invalid" diagnostics) need string-matching the output.
+        if self.returncode != 0:
+            return False
+        haystack = (self.stdout or "") + "\n" + (self.stderr or "")
+        # The import's own verdict line is authoritative. SQLcl 26.1 prints
+        # APEXLang compile WARNINGS (e.g. "Invalid template option value")
+        # for unrelated pages and still imports fine — token-scanning alone
+        # would flag those as failures.
+        success_markers = ("importação bem-sucedida", "import successful")
+        if any(s in haystack.lower() for s in success_markers):
+            return True
+        bad_tokens = (
+            "ORA-", "PLS-", "SP2-",
+            "SQL Error",
+            "inválido", "invalid",                # PT/EN: invalid argument / workspace
+            "Falha", "failure",
+            "Erro de", "Error:",
+            "Token inesperado",                   # SQLcl parse error
+        )
+        return not any(t.lower() in haystack.lower() for t in bad_tokens)
+
+
+def run_apex_import(
+    sqlcl_path: str,
+    connection: str,
+    workspace: str,
+    input_path: Path,
+    deployment: Path | None = None,
+) -> ImportResult:
+    """Invoke `sql apex import -workspace <ws> -input <app_root>` against a
+    named SQLcl connection. Returns the captured stdout/stderr.
+
+    `input_path` must be the APP ROOT of a split export — the directory
+    holding `application.apx`, `pages/` and `shared-components/`. SQLcl's
+    `-input` only accepts a single FILE when that file contains the WHOLE
+    application; importing one page's .apx standalone fails with
+    REFERENCE_NOT_FOUND on theme references such as `@/text`, because the
+    shared components the page points at aren't in the input.
+
+    `deployment` optionally points at a deployments/*.json manifest (sets
+    the target application id and runtime options).
+
+    Connection MUST already exist in the user's SQLcl connection manager
+    (the same `connect -name <NAME>` pattern used elsewhere in the project).
+    SQLcl 26.1+ is required for the `apex import` subcommand — older
+    standalone SQLcl installations don't ship it.
+    """
+    sql = os.path.expandvars(sqlcl_path)
+    if not Path(sql).is_file():
+        return ImportResult(
+            returncode=127, stdout="",
+            stderr=f"SQLcl not found at {sql}. "
+                   f"Override with --sqlcl <path>.",
+        )
+
+    dep = f" -deployment {deployment}" if deployment else ""
+    script = (
+        f"set echo off\n"
+        f"set feedback on\n"
+        f"connect -name {connection}\n"
+        f"apex import -workspace {workspace} -input {input_path}{dep}\n"
+        f"exit\n"
+    )
+    proc = subprocess.run(
+        [sql, "/nolog"],
+        input=script, capture_output=True, text=True, timeout=300,
+    )
+    # SQLcl exits 0 even when `connect -name` fails (Unknown connection /
+    # SP2-0640: not connected) — the `apex import` then runs against no
+    # session and is a silent no-op. Detect that and surface a real failure
+    # so callers don't report "returned code 0" as success.
+    combined = ((proc.stdout or "") + "\n" + (proc.stderr or "")).lower()
+    conn_markers = (
+        "unknown connection", "sp2-0640", "not connected", "não conectado",
+        "nao conectado",
+    )
+    rc = proc.returncode
+    if rc == 0 and any(m in combined for m in conn_markers):
+        rc = 2
+        extra = (f"\n[baucli] SQLcl could not open named connection "
+                 f"'{connection}'. Check bau.toml [connection].name (or "
+                 f"--connection) against your SQLcl connections "
+                 f"(`sql -name {connection}` / connmgr list).")
+        return ImportResult(returncode=rc,
+                            stdout=proc.stdout,
+                            stderr=(proc.stderr or "") + extra)
+    return ImportResult(
+        returncode=rc,
+        stdout=proc.stdout,
+        stderr=proc.stderr,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# File discovery
+# ─────────────────────────────────────────────────────────────────────────────
+def _resolve_root_and_appdir(start: Path, app_dir: str) -> tuple[Path | None, str]:
+    """Walk up from `start` looking for the first ancestor that contains
+    `apex/<app_dir>/pages/`. Returns `(ancestor, effective_app_dir)` or
+    `(None, app_dir)` if not found.
+
+    This lets the user run from any subdirectory of the project — instead
+    of failing because cwd happened to be `demo_crm/teste/` while the app
+    lives in `demo_crm/apex/...`.
+
+    Two UX tolerances on `app_dir`:
+      * a leading `apex/` is stripped (`--app-dir apex/app_104` works);
+      * when `apex/<app_dir>` exists but holds the pages one level deeper
+        in a SINGLE subdirectory (SQLcl split exports nest the app under
+        its alias, e.g. `app_104/demo-crm/pages`), that child is
+        auto-selected.
+    """
+    app_dir = app_dir.strip("/")
+    if app_dir.startswith("apex/"):
+        app_dir = app_dir[5:]
+    for d in [start, *start.parents]:
+        base = d / "apex" / app_dir
+        if (base / "pages").is_dir():
+            return d, app_dir
+        if base.is_dir():
+            kids = [k for k in sorted(base.iterdir())
+                    if k.is_dir() and (k / "pages").is_dir()]
+            if len(kids) == 1:
+                return d, f"{app_dir}/{kids[0].name}"
+    return None, app_dir
+
+
+def _resolve_project_root(start: Path, app_dir: str) -> Path | None:
+    """Backward-compatible wrapper over `_resolve_root_and_appdir`."""
+    root, _ = _resolve_root_and_appdir(start, app_dir)
+    return root
+
+
+def find_pages_referencing(
+    project_root: Path, app_dir: str, tables: Iterable[str] = ()
+) -> tuple[Path, list[Path]]:
+    """Find every .apx in `<project>/apex/<app_dir>/pages/` whose source
+    references any of the given tables (as detected by `discover_tables`).
+
+    Used by the directory-wide rebuild modes:
+      * `--table FOO` (no --page) sweeps every page where FOO appears in a
+        `tableName:` line or a `FROM/JOIN` clause;
+      * NO --table and NO --page sweeps EVERY page in the app — pass an
+        empty `tables` and all .apx files are returned (pages whose tables
+        aren't in BAU are skipped later by the rebuild loop).
+
+    Returns `(resolved_root, sorted_list_of_apx_paths)`.
+    """
+    resolved, app_dir = _resolve_root_and_appdir(project_root, app_dir)
+    if resolved is None:
+        chain = [str(d / "apex" / app_dir / "pages") for d in
+                 [project_root, *project_root.parents][:5]]
+        raise FileNotFoundError(
+            f"App directory '{app_dir}' has no pages folder under cwd or any "
+            f"of its parents. Tried (closest first):\n  - "
+            + "\n  - ".join(chain)
+        )
+    targets = {t.upper() for t in tables}
+    pages_dir = resolved / "apex" / app_dir / "pages"
+    matches: list[Path] = []
+    for f in sorted(pages_dir.glob("*.apx")):
+        if not targets:
+            matches.append(f)
+            continue
+        try:
+            txt = f.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        if targets & set(discover_tables(txt)):
+            matches.append(f)
+    return resolved, matches
+
+
+def find_apex_file(
+    project_root: Path, app_dir: str, page_id: int
+) -> tuple[Path, Path]:
+    """Locate the .apx file for one page inside an app directory.
+
+    The convention is `<project-root>/apex/<app_dir>/pages/p<padded>-*.apx`.
+    `project_root` is treated as a *hint*: if `apex/<app_dir>/pages/` isn't
+    directly under it, we walk up looking for the closest ancestor that has
+    it. Returns `(resolved_root, apex_file_path)` so the caller can render
+    paths relative to the actually-used root.
+    """
+    padded = f"p{page_id:05d}-*.apx"
+    resolved, app_dir = _resolve_root_and_appdir(project_root, app_dir)
+    if resolved is None:
+        # Show the chain we walked so the user can see where we looked.
+        chain = [str(d / "apex" / app_dir / "pages") for d in
+                 [project_root, *project_root.parents][:5]]
+        raise FileNotFoundError(
+            f"App directory '{app_dir}' has no pages folder under cwd or any "
+            f"of its parents. Tried (closest first):\n  - "
+            + "\n  - ".join(chain)
+            + f"\nHint: cd to your project root or pass --project-root "
+              f"<path-containing-apex/>."
+        )
+    pages = resolved / "apex" / app_dir / "pages"
+    candidates = list(pages.glob(padded))
+    if not candidates:
+        raise FileNotFoundError(
+            f"No .apx for page {page_id} in {pages.relative_to(resolved)} "
+            f"(looked for {padded})."
+        )
+    if len(candidates) > 1:
+        listing = "\n  - ".join(str(p.relative_to(resolved)) for p in candidates)
+        raise FileNotFoundError(
+            f"Multiple .apx files match page {page_id}:\n  - {listing}"
+        )
+    return resolved, candidates[0]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Block extraction — finds `pageItem NAME (`, `column NAME (`, etc.
+# ─────────────────────────────────────────────────────────────────────────────
+_BLOCK_RE = re.compile(
+    r"""
+    ^([ \t]*)                       # leading indent
+    (pageItem|column|displayColumn) # block type
+    [ \t]+
+    ([A-Za-z_][A-Za-z0-9_]*)        # block name
+    [ \t]*\(                        # opening paren
+    """,
+    re.VERBOSE | re.MULTILINE,
+)
+
+
+@dataclass
+class Block:
+    kind: str           # 'pageItem' | 'column' | 'displayColumn'
+    name: str
+    indent: str
+    start: int          # offset of the opening `(` line in the source
+    end: int            # offset just past the matching `)`
+    text: str           # the full block text (from indent to closing `)`)
+
+    @property
+    def bau_key(self) -> str:
+        """Column name to look up in BAU metadata.
+
+        pageItem names usually follow P<page>_<COLUMN_NAME>; strip the
+        prefix when present so e.g. `P13_DOMAIN_CODE` matches BAU column
+        `DOMAIN_CODE`.
+        """
+        n = self.name.upper()
+        m = re.match(r"^P\d+_(.+)$", n)
+        return (m.group(1) if m else n)
+
+
+def find_matching_paren(text: str, open_idx: int) -> int:
+    """Return offset just past the `)` that matches the `(` at `open_idx`.
+
+    Walks the buffer char by char, tracks paren depth, and skips over double-
+    quoted string literals and ```-fenced multi-line strings (used by
+    APEXLang for embedded SQL). Comments aren't expected inside block bodies.
+    """
+    assert text[open_idx] == "(", f"expected '(' at {open_idx}"
+    depth = 1
+    i = open_idx + 1
+    n = len(text)
+    while i < n:
+        c = text[i]
+        # SQL/MD-style triple-backtick block — skip until closing fence.
+        if c == "`" and text[i : i + 3] == "```":
+            end = text.find("```", i + 3)
+            i = (end + 3) if end != -1 else n
+            continue
+        # Double-quoted string literal — APEXLang doesn't typically use these,
+        # but a defensive skip protects against false-positive parens inside.
+        if c == '"':
+            i = _skip_quoted(text, i, '"') + 1
+            continue
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+            if depth == 0:
+                return i + 1
+        i += 1
+    raise ValueError(f"unbalanced paren starting at offset {open_idx}")
+
+
+def _skip_quoted(text: str, start: int, quote: str) -> int:
+    """Return the offset of the closing quote (matching `quote`), supporting
+    backslash escapes. If unterminated, returns len(text)-1."""
+    i = start + 1
+    n = len(text)
+    while i < n:
+        if text[i] == "\\" and i + 1 < n:
+            i += 2
+            continue
+        if text[i] == quote:
+            return i
+        i += 1
+    return n - 1
+
+
+def iter_blocks(source: str, kinds: Iterable[str] = ("pageItem", "column",
+                                                      "displayColumn")
+                ) -> list[Block]:
+    """Return every `kind NAME ( ... )` block in source, in file order."""
+    kinds = set(kinds)
+    out: list[Block] = []
+    for m in _BLOCK_RE.finditer(source):
+        if m.group(2) not in kinds:
+            continue
+        open_paren = source.find("(", m.end() - 1)
+        if open_paren == -1:
+            continue
+        try:
+            end = find_matching_paren(source, open_paren)
+        except ValueError:
+            continue
+        out.append(Block(
+            kind=m.group(2),
+            name=m.group(3),
+            indent=m.group(1),
+            start=m.start(),
+            end=end,
+            text=source[m.start():end],
+        ))
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Block-level edits — operate on the block text only, return the new text.
+# Each editor is idempotent: running twice gives the same result.
+# ─────────────────────────────────────────────────────────────────────────────
+_KV_RE = lambda key: re.compile(
+    rf"^([ \t]*){re.escape(key)}\s*:\s*(.*?)$", re.MULTILINE
+)
+
+
+def _insert_before_close_line(block: str, insertion: str) -> str:
+    """Insert `insertion` (already newline-terminated) on its own line(s)
+    immediately before the line that contains the block's closing `)`.
+
+    Splicing at the bare `block.rfind(")")` would land AFTER the closing
+    paren's own indent, doubling the leading whitespace of every line in
+    the insertion. Walking back to the start of that line first puts the
+    new content on its own lines, with the `)` line untouched.
+    """
+    close = block.rfind(")")
+    line_start = block.rfind("\n", 0, close) + 1  # 0 if no newline (shouldn't happen)
+    return block[:line_start] + insertion + block[line_start:]
+
+
+# For each block the engine may insert, which sibling blocks MUST come
+# after it according to APEX MMD 26's parser. Insertion is placed
+# immediately before the first matching successor found in the column
+# body. When no successor is found, falls back to inserting just before
+# the closing `)` of the parent.
+#
+# Modeling chose this map-of-successors over a single global ordering
+# because empirically the 2,186 column blocks in the project's sample
+# apps disagree on edge cases (e.g. some have `settings → layout`,
+# others have `layout → settings`). What the parser cares about is the
+# specific pairings that violate the schema — and the only one we keep
+# bumping into is `appearance` after `source`. The successor lists below
+# encode every such constraint relevant to the blocks we insert,
+# avoiding false confidence in a globally-unique canonical order.
+INSERT_SUCCESSORS: dict[str, tuple[str, ...]] = {
+    "heading":    ("layout", "lov", "settings", "validation",
+                   "appearance", "link", "source", "advanced", "security"),
+    "layout":     ("lov", "settings", "validation",
+                   "appearance", "link", "source", "advanced", "security"),
+    "appearance": ("source", "advanced", "security",
+                   "exportPrinting", "sorting", "columnFilter"),
+    # `settings` precedes layout/source/etc. in EVERY sampled export
+    # (409 settings→layout pairs, zero reversed).
+    "settings":   ("layout", "lov", "validation", "appearance", "link",
+                   "source", "advanced", "security", "sessionState",
+                   "default", "columnFilter", "sorting", "exportPrinting"),
+    # pageItem order in the samples: label → lov → layout → ...
+    "lov":        ("layout", "validation", "appearance", "link", "source",
+                   "advanced", "security", "sessionState", "default"),
+    # `default` is a late block (after source/appearance) but before
+    # security/advanced/help — place it ahead of the first of those present.
+    "default":    ("security", "advanced", "help"),
+    # `help` is the LAST nested block in the samples (259 ✕→help pairs
+    # dominate) — the empty successor list makes the fallback ("insert
+    # before the closing paren") land it exactly there.
+    "help":       (),
+}
+
+
+# Server-side / expression defaults that must NOT become a form item default
+# — they are applied by the DB on INSERT, not chosen in the UI. The safe
+# filter accepts ONLY a quoted string literal or a plain number; everything
+# else (sequences, SYSDATE/SYSTIMESTAMP, SYS_GUID(), USER, expressions, bare
+# identifiers) is rejected.
+def _safe_default(raw: str | None) -> str | None:
+    """Return a UI-safe literal from a raw DB DATA_DEFAULT, or None when the
+    default is server-side / an expression. Strips the quotes of a string
+    literal ('S' → S) and passes numbers through (0, -1, 1.5)."""
+    if not raw:
+        return None
+    v = raw.strip()
+    if not v:
+        return None
+    m = re.match(r"^'(.*)'$", v, re.DOTALL)   # quoted string literal
+    if m:
+        return m.group(1).replace("''", "'") or None
+    if re.match(r"^-?\d+(\.\d+)?$", v):        # numeric literal
+        return v
+    return None                                # anything else is unsafe
+
+
+def _insert_block_in_order(block: str, new_block_name: str,
+                           content: str) -> str:
+    """Insert `content` immediately before the first sibling listed in
+    INSERT_SUCCESSORS[new_block_name] that exists in `block`. Falls back
+    to inserting before the closing `)` when no successor is found —
+    that's safe because the parser only rejects out-of-order placement,
+    and putting a new block last when no other constraints exist matches
+    what the samples do."""
+    successors = INSERT_SUCCESSORS.get(new_block_name, ())
+    for later in successors:
+        m = re.search(
+            rf"^([ \t]*){re.escape(later)}\s*\{{",
+            block, re.MULTILINE,
+        )
+        if m:
+            return block[:m.start()] + content + block[m.start():]
+    return _insert_before_close_line(block, content)
+
+
+def _set_or_add_kv(block: str, key: str, value: str, indent: str) -> str:
+    """Set `key: value` inside block. If key already exists, replace its
+    value. Otherwise insert just before the closing `)`."""
+    if value is None:
+        return block
+    pat = _KV_RE(key)
+    if pat.search(block):
+        return pat.sub(lambda m: f"{m.group(1)}{key}: {value}", block, count=1)
+    return _insert_before_close_line(block, f"{indent}{key}: {value}\n")
+
+
+def _top_kv_match(block: str, key: str, inner_indent: str):
+    """Match `key: value` only at the block's OWN indentation level. A bare
+    multiline search for e.g. `type:` also hits the nested one inside
+    `source { type: sqlQuery }` — depth filtering by indent avoids editing
+    the wrong property."""
+    for m in _KV_RE(key).finditer(block):
+        if m.group(1) == inner_indent:
+            return m
+    return None
+
+
+def _set_top_kv(block: str, key: str, value: str, inner_indent: str) -> str:
+    """Set a block-level scalar (`type: hidden` etc.) at depth 1 only.
+    When absent, insert as the FIRST line of the block — scalar properties
+    like `type:` lead every sampled pageItem/column block, and the parser
+    can reject them after nested blocks."""
+    m = _top_kv_match(block, key, inner_indent)
+    if m:
+        return block[:m.start()] + f"{m.group(1)}{key}: {value}" + block[m.end():]
+    open_idx = block.find("(")
+    line_end = block.find("\n", open_idx)
+    if line_end == -1:
+        return _insert_before_close_line(block, f"{inner_indent}{key}: {value}\n")
+    return (block[:line_end + 1]
+            + f"{inner_indent}{key}: {value}\n"
+            + block[line_end + 1:])
+
+
+def _remove_nested_kv(block: str, parent: str, key: str) -> tuple[str, str | None]:
+    """Remove `key: ...` from inside a multi-line `parent { ... }` block.
+    Returns `(new_block, removed_value)`; `removed_value` is None when the
+    key wasn't present. When the removal leaves the parent empty, the whole
+    parent block is dropped — no sampled export carries an empty `{}`."""
+    multi_pat = re.compile(
+        rf"^([ \t]*){re.escape(parent)}\s*\{{(.*?)^\1\}}",
+        re.MULTILINE | re.DOTALL,
+    )
+    m = multi_pat.search(block)
+    if not m:
+        return block, None
+    inner = m.group(2)
+    kv = _KV_RE(key).search(inner)
+    if not kv:
+        return block, None
+    removed = kv.group(2).strip()
+    line_end = inner.find("\n", kv.end())
+    line_end = len(inner) if line_end == -1 else line_end + 1
+    new_inner = inner[:kv.start()] + inner[line_end:]
+    if not new_inner.strip():
+        end = m.end()
+        if block[end:end + 1] == "\n":
+            end += 1
+        return block[:m.start()] + block[end:], removed
+    rebuilt = f"{m.group(1)}{parent} {{{new_inner}{m.group(1)}}}"
+    return block[:m.start()] + rebuilt + block[m.end():], removed
+
+
+def _set_or_add_nested_kv(block: str, parent: str, key: str, value: str,
+                          indent: str, inner_indent: str) -> str:
+    """Set `parent { ... key: value ... }`. If parent block exists (either as
+    a multi-line block or a single-line `parent { … }`), update the key
+    inside it — expanding to multi-line form for predictable indentation.
+    If the parent block doesn't exist, insert a new multi-line block at
+    the canonical APEXLang position."""
+    if value is None:
+        return block
+
+    # Multi-line: parent { ... \n<indent>} — closing `}` on its own line.
+    multi_pat = re.compile(
+        rf"^([ \t]*){re.escape(parent)}\s*\{{(.*?)^\1\}}",
+        re.MULTILINE | re.DOTALL,
+    )
+    # Single-line: parent { ... } on one line, no nested braces inside.
+    inline_pat = re.compile(
+        rf"^([ \t]*){re.escape(parent)}\s*\{{\s*([^{{}}\n]*?)\s*\}}\s*$",
+        re.MULTILINE,
+    )
+
+    m = multi_pat.search(block)
+    is_inline = False
+    if not m:
+        m = inline_pat.search(block)
+        is_inline = m is not None
+
+    if m:
+        block_indent = m.group(1)
+        inner = m.group(2)
+        kv = _KV_RE(key)
+        if kv.search(inner):
+            new_inner = kv.sub(
+                lambda mm: f"{mm.group(1)}{key}: {value}", inner, count=1
+            )
+        else:
+            # Append the new key, preserving the existing entry indent when
+            # the block is multi-line. For inline blocks, fall back to
+            # `inner_indent` since the inner had no indentation at all.
+            existing = re.search(r"^([ \t]+)\S", inner, re.MULTILINE)
+            child_indent = existing.group(1) if existing else inner_indent
+            new_inner = inner.rstrip("\n") + f"\n{child_indent}{key}: {value}\n"
+
+        if is_inline:
+            # Expand inline → multi-line for consistent shape. The inner
+            # captured from the single-line regex has no leading newline /
+            # indentation, so rebuild it with proper indents.
+            inner_lines = [
+                ln for ln in new_inner.strip().splitlines() if ln.strip()
+            ]
+            rebuilt = "\n".join(
+                f"{inner_indent}{ln.strip()}" for ln in inner_lines
+            )
+            replacement = (
+                f"{block_indent}{parent} {{\n{rebuilt}\n{block_indent}}}"
+            )
+        else:
+            replacement = (
+                f"{block_indent}{parent} {{{new_inner}{block_indent}}}"
+            )
+        return block[:m.start()] + replacement + block[m.end():]
+
+    # parent block doesn't exist — insert at the canonical APEXLang
+    # ordering position so the parser doesn't reject it (e.g. `appearance`
+    # must come before `source` in APEX 26).
+    insertion = (
+        f"{indent}{parent} {{\n"
+        f"{inner_indent}{key}: {value}\n"
+        f"{indent}}}\n"
+    )
+    return _insert_block_in_order(block, parent, insertion)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Top-level rebuild — given source text + dict of BauColumn, return new source
+# plus a list of (column_name, what_changed) tuples.
+# ─────────────────────────────────────────────────────────────────────────────
+@dataclass
+class Change:
+    block: Block
+    field: str
+    old: str | None
+    new: str | None
+
+    def render(self) -> str:
+        # Escape `[…]` for Rich — otherwise `[pageItem …]` is consumed as
+        # markup and disappears from the terminal output. Long values
+        # (helpText carries full column descriptions) are truncated.
+        def _t(v):
+            return (v[:57] + "…") if isinstance(v, str) and len(v) > 58 else v
+        return (f"  \\[{self.block.kind} {self.block.name}] {self.field}: "
+                f"{_t(self.old)!r} → {_t(self.new)!r}")
+
+
+@dataclass
+class RebuildResult:
+    new_source: str
+    changes: list[Change] = field(default_factory=list)
+    skipped: list[tuple[str, str]] = field(default_factory=list)  # (block name, reason)
+
+
+def _quote_apexlang(s: str) -> str:
+    """APEXLang values are bare tokens or quoted with single/double quotes
+    depending on content. For labels we use the raw form (no surrounding
+    quotes) because that's what existing files in this repo do."""
+    # Strip leading/trailing whitespace; preserve PT-BR accents as-is.
+    return s.strip() if s else ""
+
+
+def rebuild_apex_source(source: str, columns: dict[str, BauColumn],
+                        rows_per_page: int | None = None) -> RebuildResult:
+    """Apply BAU column metadata to every recognized block in `source`.
+
+    When `rows_per_page` is given, every savedReport `view { rowsPerPage: N }`
+    on the page is set to it (the BAU_CONFIG DOCTAB.REPORT_ROWS_PER_PAGE value,
+    resolved by GET_COLUMNS per schema)."""
+    blocks = iter_blocks(source, kinds=("pageItem", "column", "displayColumn"))
+    # Apply from the END of the file backwards so offsets in earlier blocks
+    # remain valid as we splice text in.
+    changes: list[Change] = []
+    skipped: list[tuple[str, str]] = []
+    buf = source
+    # Columns whose IR sqlQuery projects a DERIVED value (FK shown as a name
+    # via scalar subquery, etc.) — they display a string, so numeric-ID
+    # metadata (center align / 000000 mask) must not be applied to them.
+    derived_cols = derived_display_cols(source)
+    blocks_sorted = sorted(blocks, key=lambda b: -b.start)
+
+    for blk in blocks_sorted:
+        col = columns.get(blk.bau_key)
+        if not col and blk.bau_key.endswith("_LABEL"):
+            # Domain columns are surfaced in IRs/IGs as a friendly-label
+            # alias (e.g. `ATIVO_LABEL` → FNC_BAU_DOMAIN_LABEL(...)). The
+            # alias is not a BAU column, so fall back to the base column so
+            # heading / format / align and especially REPORT_DISPLAY_ORDER
+            # (column ordering) still apply. Mirrors the conformity check's
+            # `_LABEL` normalization. Exact match wins first, so a real
+            # column literally named `*_LABEL` is never shadowed.
+            col = columns.get(blk.bau_key[:-len("_LABEL")])
+        if not col:
+            skipped.append((blk.name, "no matching BAU column"))
+            continue
+
+        # The block's text in `buf` may have shifted if we already edited
+        # something *after* it. We're walking back-to-front so all later
+        # edits are already applied to buf; we re-extract this block's text
+        # from buf using its still-valid offsets (offsets earlier in file
+        # are unaffected by later splices).
+        block_text = buf[blk.start:blk.end]
+        new_block = block_text
+        # Inner indent: best guess from first non-blank inner line.
+        first_inner = re.search(r"^([ \t]+)\S", block_text[block_text.find("(") + 1:],
+                                re.MULTILINE)
+        inner_indent = (blk.indent + "    ") if not first_inner else first_inner.group(1)
+        deep_indent = inner_indent + "    "
+
+        # ── label / heading / mask / align / hidden — most edits are
+        # skipped for `displayColumn` because that block is just a "use
+        # this column at this slot" pointer inside savedReport. Heading/
+        # mask/etc. ARE legal there (as overrides) but pages rarely set
+        # them by hand — forcing the BAU defaults in would clutter every
+        # saved report. We touch only `sequence` for displayColumn.
+
+        # Detect the block's own `type:` — depth-filtered, otherwise the
+        # nested `source { type: sqlQuery }` is matched instead.
+        type_match = _top_kv_match(new_block, "type", inner_indent)
+        block_type = type_match.group(2).strip() if type_match else None
+        block_is_hidden = (block_type == "hidden")
+        # APEX 26's parser rejects display-related properties on hidden
+        # columns/items (columnAlignment, formatMask, textCase, helpText —
+        # zero occurrences inside `type: hidden` blocks across all sampled
+        # exports). A block that BAU marks HIDDEN is flipped further below,
+        # so treat it as hidden ALREADY: skip adding those properties and
+        # strip any it carries.
+        effective_hidden = block_is_hidden or (
+            col.hidden and blk.kind != "displayColumn"
+        )
+
+        if blk.kind != "displayColumn" and effective_hidden:
+            for parent, key in (("appearance", "formatMask"),
+                                ("layout", "columnAlignment"),
+                                ("layout", "alignment")):
+                stripped, removed = _remove_nested_kv(new_block, parent, key)
+                if removed is not None:
+                    new_block = stripped
+                    changes.append(Change(blk, key, removed, None))
+            # `label` (scalar OR block form) is INVALID_PROPERTY on hidden
+            # pageItems (heading on hidden columns is fine — 190 occurrences
+            # in the samples; label inside hidden pageItems: zero).
+            if blk.kind == "pageItem":
+                lm = _top_kv_match(new_block, "label", inner_indent)
+                if lm:
+                    line_end = new_block.find("\n", lm.end())
+                    line_end = (len(new_block) if line_end == -1
+                                else line_end + 1)
+                    changes.append(
+                        Change(blk, "label", lm.group(2).strip(), None))
+                    new_block = new_block[:lm.start()] + new_block[line_end:]
+                lb = re.search(r"^([ \t]*)label\s*\{.*?^\1\}\n?",
+                               new_block, re.MULTILINE | re.DOTALL)
+                if lb:
+                    changes.append(Change(blk, "label", "{…}", None))
+                    new_block = new_block[:lb.start()] + new_block[lb.end():]
+
+        # ── form item type (pageItem only) ─────────────────────────────
+        # BAU.FORM_ITEM_TYPE is the exact APEXLang token (checkbox, switch,
+        # selectList, ...). Precedence: HIDDEN / READ_ONLY win; a page-side
+        # `type: hidden` is also left alone (the page hides items for its
+        # own reasons, e.g. dashboard filters).
+        if (blk.kind == "pageItem" and col.form_item_type
+                and not effective_hidden and not col.read_only
+                and block_type not in ("hidden", col.form_item_type)):
+            new_type = col.form_item_type
+            has_lov = re.search(r"^[ \t]*lov\s*\{", new_block, re.MULTILINE)
+            if new_type in LOV_ITEM_TYPES and not has_lov and not col.domain_values:
+                # FK lookups etc. — can't synthesize an LOV query.
+                skipped.append((blk.name,
+                                f"form_item_type {new_type} needs an lov "
+                                f"block (no BAU domain values to synthesize "
+                                f"one — FK lookup?)"))
+            else:
+                if new_type in LOV_ITEM_TYPES and not has_lov:
+                    # Synthesize a static LOV from the BAU-documented
+                    # CHECK-constraint domain (display;return pairs in the
+                    # STATIC2 grammar). `,` and `;` are structural in that
+                    # grammar — sanitized out of labels/values.
+                    def _san(s: str) -> str:
+                        return ((s or "").replace(",", " ")
+                                         .replace(";", " ").strip())
+                    pairs = ",".join(f"{_san(lbl)};{_san(val)}"
+                                     for val, lbl in col.domain_values)
+                    # Closed CHECK domain → NULL is never a valid member, so
+                    # the synthesized LOV must NOT offer a null option
+                    # (`displayNullValue: false`); otherwise APEX renders an
+                    # empty radio/entry that can't be saved on a NOT NULL flag.
+                    lov_block = (
+                        f"{inner_indent}lov {{\n"
+                        f"{deep_indent}type: staticValues\n"
+                        f"{deep_indent}staticValues: STATIC2:{pairs}\n"
+                        f"{deep_indent}displayExtraValues: false\n"
+                        f"{deep_indent}displayNullValue: false\n"
+                        f"{inner_indent}}}\n"
+                    )
+                    new_block = _insert_block_in_order(new_block, "lov",
+                                                       lov_block)
+                    changes.append(
+                        Change(blk, "lov", None, f"STATIC2:{pairs}"))
+                    has_lov = True
+                # type-specific child blocks don't survive a retype: a
+                # leftover lov on a checkbox (or textField settings on a
+                # selectList) is INVALID_PROPERTY at import.
+                if new_type not in LOV_ITEM_TYPES and has_lov:
+                    lov_m = re.search(r"^([ \t]*)lov\s*\{.*?^\1\}\n?",
+                                      new_block, re.MULTILINE | re.DOTALL)
+                    if lov_m:
+                        changes.append(Change(blk, "lov", "{…}", None))
+                        new_block = (new_block[:lov_m.start()]
+                                     + new_block[lov_m.end():])
+                set_m = re.search(r"^([ \t]*)settings\s*\{.*?^\1\}\n?",
+                                  new_block, re.MULTILINE | re.DOTALL)
+                if set_m:
+                    changes.append(Change(blk, "settings", "{…}", None))
+                    new_block = (new_block[:set_m.start()]
+                                 + new_block[set_m.end():])
+                new_block = _set_top_kv(new_block, "type", new_type,
+                                        inner_indent)
+                changes.append(Change(blk, "type", block_type, new_type))
+                block_type = new_type
+
+                # Single checkbox numa coluna com domínio: o strip de settings
+                # acima removeu os valores antigos e checkbox não usa lov —
+                # sem checkedValue/uncheckedValue o item envia valor inválido e
+                # viola o CHECK da coluna (ex.: CK_..._ATIVO: ATIVO IN ('S','N')).
+                # Sintetiza o settings a partir do domínio documentado.
+                if new_type == "checkbox":
+                    if len(col.domain_values) == 2:
+                        _truthy = {"S", "Y", "1", "T", "SIM", "YES", "TRUE", "ATIVO"}
+                        _vals = [val for val, _lbl in col.domain_values]
+                        _checked = next((v for v in _vals
+                                         if (v or "").upper() in _truthy), _vals[0])
+                        _unchecked = next((v for v in _vals if v != _checked),
+                                          _vals[-1])
+                        settings_block = (
+                            f"{inner_indent}settings {{\n"
+                            f"{deep_indent}useDefaults: false\n"
+                            f"{deep_indent}checkedValue: {_checked}\n"
+                            f"{deep_indent}uncheckedValue: {_unchecked}\n"
+                            f"{inner_indent}}}\n"
+                        )
+                        new_block = _insert_block_in_order(
+                            new_block, "settings", settings_block)
+                        changes.append(Change(blk, "settings", None,
+                                              f"checked={_checked}/unchecked={_unchecked}"))
+                    else:
+                        # domínio não-booleano (≠ 2 valores) não cabe num single
+                        # checkbox — deixa selectList/radioGroup tratar via lov.
+                        skipped.append((blk.name,
+                                        f"checkbox requer domínio booleano (2 valores); "
+                                        f"a coluna tem {len(col.domain_values)} — "
+                                        f"considere FORM_ITEM_TYPE=selectList"))
+
+        # Self-heal stray `appearance { height: N }`: it is only valid on
+        # multi-row types (textarea / editors). On any other pageItem it is
+        # INVALID_PROPERTY at import and aborts the whole app import. Run
+        # this regardless of whether a retype happened THIS run, so files a
+        # previous rebuild left with e.g. a radioGroup + height:1 self-heal
+        # on the next pass (the retype branch above won't re-fire once the
+        # type already matches).
+        if (blk.kind == "pageItem" and block_type
+                and block_type not in HEIGHT_ITEM_TYPES):
+            new_block, removed_h = _remove_nested_kv(
+                new_block, "appearance", "height")
+            if removed_h is not None:
+                changes.append(Change(blk, "height", removed_h, None))
+
+        # Self-heal NULL option on closed-domain LOV items: a CHECK domain is
+        # a closed set (NULL is never a member), so a selectList/radioGroup/etc.
+        # over it must carry `lov { displayNullValue: false }`. Without it APEX
+        # shows an empty entry that can't be saved on a NOT NULL flag. Runs
+        # regardless of retype, so items a previous rebuild synthesized without
+        # it (or hand-built static LOVs) self-heal on the next pass.
+        if (blk.kind == "pageItem" and block_type in LOV_ITEM_TYPES
+                and col.domain_values):
+            has_static = re.search(
+                r"^[ \t]*lov\s*\{[^}]*staticValues",
+                new_block, re.MULTILINE | re.DOTALL)
+            has_null_kv = re.search(
+                r"^[ \t]*lov\s*\{.*?displayNullValue",
+                new_block, re.MULTILINE | re.DOTALL)
+            if has_static and not has_null_kv:
+                new_block = _set_or_add_nested_kv(
+                    new_block, "lov", "displayNullValue", "false",
+                    inner_indent, deep_indent)
+                changes.append(Change(blk, "displayNullValue", None, "false"))
+
+        # Default do item de formulário: form_default (regra/explícito, usado
+        # como-está) > data_default do banco filtrado a literais. Só em itens
+        # editáveis (não hidden/displayOnly/RO/PK — defaults ali não fazem
+        # sentido ou são server-side). Idempotente: só escreve se mudou.
+        if (blk.kind == "pageItem" and not effective_hidden
+                and not col.read_only and not col.is_pk
+                and block_type not in ("hidden", "displayOnly")):
+            eff_default = ((col.form_default or "").strip() or None) \
+                or _safe_default(col.data_default)
+            if eff_default is not None:
+                sv = (eff_default if re.match(r"^[A-Za-z0-9_.\-]+$", eff_default)
+                      else _quote_apexlang(eff_default))
+                cur_default = None
+                dm = re.search(r"^([ \t]*)default\s*\{.*?^\1\}",
+                               new_block, re.MULTILINE | re.DOTALL)
+                if dm:
+                    sm = _KV_RE("staticValue").search(dm.group(0))
+                    cur_default = sm.group(2).strip() if sm else None
+                if cur_default != sv:
+                    new_block = _set_or_add_nested_kv(
+                        new_block, "default", "type", "static",
+                        inner_indent, deep_indent)
+                    new_block = _set_or_add_nested_kv(
+                        new_block, "default", "staticValue", sv,
+                        inner_indent, deep_indent)
+                    changes.append(Change(blk, "default", cur_default, sv))
+
+        if blk.kind != "displayColumn" and col.label:
+            new_label = _quote_apexlang(col.label)
+            if blk.kind == "pageItem":
+                if effective_hidden:
+                    pass  # label is INVALID_PROPERTY on hidden pageItems
+                else:
+                    # APEXLang has TWO label forms: the scalar `label: X`
+                    # and a `label { label: X; alignment: ... }` block
+                    # (used whenever the label carries extra attributes —
+                    # 665 alignment-in-label occurrences in the samples).
+                    # Prefer the block when present; both forms on the same
+                    # item is INVALID_PROPERTY, so a stray scalar next to a
+                    # block is removed (self-repair).
+                    lbl_blk_re = re.compile(
+                        r"^([ \t]*)label\s*\{(.*?)^\1\}",
+                        re.MULTILINE | re.DOTALL,
+                    )
+                    bm = lbl_blk_re.search(new_block)
+                    scalar_m = _top_kv_match(new_block, "label", inner_indent)
+                    if bm and scalar_m:
+                        line_end = new_block.find("\n", scalar_m.end())
+                        line_end = (len(new_block) if line_end == -1
+                                    else line_end + 1)
+                        changes.append(Change(
+                            blk, "label",
+                            scalar_m.group(2).strip(), "(dup scalar removed)"))
+                        new_block = (new_block[:scalar_m.start()]
+                                     + new_block[line_end:])
+                        bm = lbl_blk_re.search(new_block)
+                        scalar_m = None
+                    if bm:
+                        kv = _KV_RE("label").search(bm.group(2))
+                        old_label = kv.group(2).strip() if kv else None
+                        if old_label != new_label:
+                            new_block = _set_or_add_nested_kv(
+                                new_block, "label", "label", new_label,
+                                inner_indent, deep_indent,
+                            )
+                            changes.append(
+                                Change(blk, "label", old_label, new_label))
+                    else:
+                        old_label = (scalar_m.group(2).strip()
+                                     if scalar_m else None)
+                        if old_label != new_label:
+                            if scalar_m:
+                                new_block = (
+                                    new_block[:scalar_m.start()]
+                                    + f"{inner_indent}label: {new_label}"
+                                    + new_block[scalar_m.end():]
+                                )
+                            elif type_match:
+                                # samples order scalars `type:` then
+                                # `label:` — insert after the type line
+                                le = new_block.find("\n", type_match.end())
+                                at = len(new_block) if le == -1 else le + 1
+                                new_block = (
+                                    new_block[:at]
+                                    + f"{inner_indent}label: {new_label}\n"
+                                    + new_block[at:]
+                                )
+                            else:
+                                new_block = _set_top_kv(
+                                    new_block, "label", new_label,
+                                    inner_indent)
+                            changes.append(
+                                Change(blk, "label", old_label, new_label))
+            else:  # column / displayColumn — heading is nested
+                inner = re.search(
+                    r"^([ \t]*)heading\s*\{(.*?)^\1\}",
+                    new_block, re.MULTILINE | re.DOTALL,
+                )
+                old_heading_val = None
+                if inner:
+                    kv = _KV_RE("heading").search(inner.group(2))
+                    if kv:
+                        old_heading_val = kv.group(2).strip()
+                if old_heading_val != new_label:
+                    new_block = _set_or_add_nested_kv(
+                        new_block, "heading", "heading", new_label,
+                        inner_indent, deep_indent,
+                    )
+                    changes.append(Change(blk, "heading", old_heading_val, new_label))
+
+        # ── help text (pageItem only) ──────────────────────────────────
+        # BAU.DESCRIPTION → `help { helpText: ... }`. The value is a free
+        # single-line token in APEXLang, so multi-line descriptions are
+        # collapsed. IR/IG `column` blocks have no help property.
+        if (blk.kind == "pageItem" and col.description
+                and not effective_hidden):
+            help_text = " ".join(col.description.split())
+            inner_help = re.search(
+                r"^([ \t]*)help\s*\{(.*?)^\1\}",
+                new_block, re.MULTILINE | re.DOTALL,
+            )
+            old_help = None
+            if inner_help:
+                kv = _KV_RE("helpText").search(inner_help.group(2))
+                if kv:
+                    old_help = kv.group(2).strip()
+            if old_help != help_text:
+                new_block = _set_or_add_nested_kv(
+                    new_block, "help", "helpText", help_text,
+                    inner_indent, deep_indent,
+                )
+                changes.append(Change(blk, "helpText", old_help, help_text))
+
+        # ── text case ──────────────────────────────────────────────────
+        # BAU.TEXT_CASE U/L → `settings { textCase: upper|lower }`. Only
+        # `type: textField` blocks carry the property in the samples;
+        # other item types reject it.
+        if (blk.kind != "displayColumn" and not effective_hidden
+                and col.text_case in TEXT_CASE_MAP
+                and block_type == "textField"):
+            mapped_case = TEXT_CASE_MAP[col.text_case]
+            inner_settings = re.search(
+                r"^([ \t]*)settings\s*\{(.*?)^\1\}",
+                new_block, re.MULTILINE | re.DOTALL,
+            )
+            old_case = None
+            if inner_settings:
+                kv = _KV_RE("textCase").search(inner_settings.group(2))
+                if kv:
+                    old_case = kv.group(2).strip()
+            if old_case != mapped_case:
+                new_block = _set_or_add_nested_kv(
+                    new_block, "settings", "textCase", mapped_case,
+                    inner_indent, deep_indent,
+                )
+                changes.append(Change(blk, "textCase", old_case, mapped_case))
+
+        # ── LOV-rendered column/item → display is a STRING ─────────────
+        # A column/item shown through an LOV (e.g. an FK *_ID rendered as the
+        # referenced NAME, or a select list) displays a lookup string. BAU's
+        # metadata describes the underlying numeric ID (center align + a
+        # numeric mask like 000000), which is wrong for a string. Detect the
+        # `lov { }` block (present for IR LOV columns; synthesized above for
+        # retyped select lists) and: drop the numeric mask + force left align.
+        # `lov { }` block → unambiguous string display. A SQL-derived
+        # projection (subquery/function aliased to the column) is treated as a
+        # string display ONLY when the column looks like a numeric ID — the
+        # "ID shown as the looked-up name" case the numeric-ID metadata
+        # (center align + 0000 mask) is wrong for. ID signature: FK/PK flags
+        # (often unset when constraints aren't synced), OR center align, OR an
+        # all-zeros mask, OR an ID-style name (ID / *_ID / ID_*). This avoids
+        # touching a derived NUMERIC measure (e.g. `(qtd*preco) VALOR`, right
+        # align + decimal mask), which matches none of these.
+        _id_like = (col.is_fk or col.is_pk
+                    or (col.align_report or "").upper() == "C"
+                    or bool(re.fullmatch(r"0+", col.format_mask or ""))
+                    or bool(re.search(r"(^ID$|_ID$|^ID_)", blk.name.upper())))
+        block_has_lov = bool(
+            re.search(r"^[ \t]*lov\s*\{", new_block, re.MULTILINE)) \
+            or (blk.name.upper() in derived_cols and _id_like)
+        if (blk.kind != "displayColumn" and block_has_lov
+                and not effective_hidden):
+            stripped, removed = _remove_nested_kv(
+                new_block, "appearance", "formatMask")
+            if removed is not None:
+                new_block = stripped
+                changes.append(Change(blk, "formatMask", removed, None))
+
+        # ── format mask ────────────────────────────────────────────────
+        # Skipped on hidden blocks — APEX 26 raises INVALID_PROPERTY — and on
+        # LOV columns (the displayed value is a string, not the numeric ID).
+        if (blk.kind != "displayColumn" and col.format_mask
+                and not effective_hidden and not block_has_lov):
+            old_mask_m = re.search(
+                r"^[ \t]*formatMask\s*:\s*(.*?)$", new_block, re.MULTILINE
+            )
+            old_mask = old_mask_m.group(1).strip() if old_mask_m else None
+            if old_mask != col.format_mask:
+                new_block = _set_or_add_nested_kv(
+                    new_block, "appearance", "formatMask", col.format_mask,
+                    inner_indent, deep_indent,
+                )
+                changes.append(Change(blk, "formatMask", old_mask, col.format_mask))
+
+        # ── alignment ──────────────────────────────────────────────────
+        # Also skipped on hidden blocks (same parser rule as formatMask).
+        # pageItem and column use DIFFERENT keys and vocabularies — see
+        # ALIGN_MAP / ALIGN_MAP_ITEM.
+        if blk.kind == "pageItem":
+            align_src, align_key, amap = col.align_form, "alignment", ALIGN_MAP_ITEM
+        else:
+            align_src, align_key, amap = col.align_report, "columnAlignment", ALIGN_MAP
+        # LOV columns show a string → left-align, overriding BAU's numeric-ID
+        # center default (see the LOV/format-mask note above).
+        if block_has_lov:
+            align_src = "L"
+        if (blk.kind != "displayColumn" and align_src in amap
+                and not effective_hidden):
+            mapped = amap[align_src]
+            old_align_m = re.search(
+                rf"^[ \t]*{align_key}\s*:\s*(.*?)$", new_block, re.MULTILINE
+            )
+            old_align = old_align_m.group(1).strip() if old_align_m else None
+            # `start` is the IR column default: APEX's import round-trip
+            # drops an explicit `columnAlignment: start`, so writing it
+            # would re-surface as phantom drift on every following run.
+            if (blk.kind == "column" and old_align is None
+                    and mapped == "start"):
+                pass
+            elif old_align != mapped:
+                new_block = _set_or_add_nested_kv(
+                    new_block, "layout", align_key, mapped,
+                    inner_indent, deep_indent,
+                )
+                changes.append(Change(blk, align_key, old_align, mapped))
+
+        # ── hidden / readOnly ──────────────────────────────────────────
+        # `_set_top_kv` edits the block's OWN `type:` (depth-filtered), not
+        # the nested `source { type: ... }`.
+        if blk.kind != "displayColumn" and col.hidden:
+            if block_type != "hidden":
+                new_block = _set_top_kv(new_block, "type", "hidden",
+                                        inner_indent)
+                changes.append(Change(blk, "type", block_type, "hidden"))
+        elif col.read_only and blk.kind not in ("pageItem", "displayColumn"):
+            if block_type not in (None, "displayOnly"):
+                # leave non-displayOnly types alone (e.g. textField with explicit RO)
+                pass
+            elif block_type != "displayOnly":
+                new_block = _set_top_kv(new_block, "type", "displayOnly",
+                                        inner_indent)
+                changes.append(Change(blk, "type", block_type, "displayOnly"))
+
+        # ── sequence (block ordering) ──────────────────────────────────
+        # BAU's REPORT_DISPLAY_ORDER / FORM_DISPLAY_ORDER are the FINAL
+        # sequence values: PRC_BAU_DOCTAB_ORDER_COLUMNS already steps them
+        # by 10 (10, 20, 30 …) precisely so manual insertions fit between.
+        # Use them verbatim — multiplying again double-stepped the sequence
+        # (e.g. 70 → 700). All three block kinds consume the stored value
+        # directly (savedReport `displayColumn` always did).
+        target_seq = None
+        if blk.kind == "pageItem" and col.form_display_order is not None:
+            target_seq = col.form_display_order
+        elif blk.kind == "column" and col.report_display_order is not None:
+            target_seq = col.report_display_order
+        elif blk.kind == "displayColumn" and col.report_display_order is not None:
+            target_seq = col.report_display_order
+
+        if target_seq is not None:
+            if blk.kind == "displayColumn":
+                # `sequence: N` directly inside the displayColumn block
+                seq_m = _KV_RE("sequence").search(new_block)
+                old_seq = seq_m.group(2).strip() if seq_m else None
+                target_str = str(target_seq)
+                if old_seq != target_str:
+                    new_block = _set_or_add_kv(new_block, "sequence",
+                                               target_str, inner_indent)
+                    changes.append(Change(blk, "sequence", old_seq, target_str))
+            else:
+                # layout { sequence: N }
+                layout_re = re.compile(
+                    r"^([ \t]*)layout\s*\{(.*?)^\1\}",
+                    re.MULTILINE | re.DOTALL,
+                )
+                lm = layout_re.search(new_block)
+                old_seq = None
+                if lm:
+                    kv = _KV_RE("sequence").search(lm.group(2))
+                    if kv:
+                        old_seq = kv.group(2).strip()
+                target_str = str(target_seq)
+                if old_seq != target_str:
+                    new_block = _set_or_add_nested_kv(
+                        new_block, "layout", "sequence", target_str,
+                        inner_indent, deep_indent,
+                    )
+                    changes.append(Change(blk, "sequence", old_seq, target_str))
+
+        # Splice back into the buffer.
+        buf = buf[:blk.start] + new_block + buf[blk.end:]
+
+    changes = list(reversed(changes))
+
+    # rowsPerPage dos IRs: seta todo `view { rowsPerPage: N }` do page para o
+    # valor de config (só aparece em savedReport de interactiveReport). Feito
+    # no buffer final (é region-level, fora dos blocos de coluna/item).
+    if rows_per_page and rows_per_page > 0:
+        rpp_blk = Block("savedReport", "view", "", 0, 0, "")
+
+        def _sub_rpp(m):
+            if m.group(2) != str(rows_per_page):
+                changes.append(Change(rpp_blk, "rowsPerPage",
+                                      m.group(2), str(rows_per_page)))
+            return f"{m.group(1)}{rows_per_page}"
+
+        buf = re.sub(r"(rowsPerPage:\s*)(\d+)", _sub_rpp, buf)
+
+    return RebuildResult(new_source=buf, changes=changes, skipped=skipped)