acumatica-cli 0.16.0__tar.gz → 0.18.0__tar.gz

{acumatica_cli-0.16.0 → acumatica_cli-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acumatica-cli
-Version: 0.16.0
+Version: 0.18.0
 Summary: Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data
 Author: Konstantin Borovik
 Author-email: Konstantin Borovik <kb@lab5.ca>
@@ -107,6 +107,8 @@ A path like `config/` expands nested seed dirs in that fixed order.
 `extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
 `inventory` is offline (no REST/SSH/password): SM203520 Settings XML ZIP or `ac.exe export xml` folder writes to `inventory/`.
 `reconcile` is offline: compare `inventory/` to optional `config/` and write `findings/` only (never writes seed).
+Optional `snapshot_map.yaml` (data-repo root or package defaults) maps DAC tables to catalog entities and normalizes join (pad-trim, key/field aliases, Account/Sub FK CD resolve, enum label→code).
+See [docs/demo-seed.md](docs/demo-seed.md).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 

{acumatica_cli-0.16.0 → acumatica_cli-0.18.0}/README.md

@@ -89,6 +89,8 @@ A path like `config/` expands nested seed dirs in that fixed order.
 `extract` always writes under `config/{bootstrap,baseline,setup,master}/` (catalog-driven; never root SEED_DIRS).
 `inventory` is offline (no REST/SSH/password): SM203520 Settings XML ZIP or `ac.exe export xml` folder writes to `inventory/`.
 `reconcile` is offline: compare `inventory/` to optional `config/` and write `findings/` only (never writes seed).
+Optional `snapshot_map.yaml` (data-repo root or package defaults) maps DAC tables to catalog entities and normalizes join (pad-trim, key/field aliases, Account/Sub FK CD resolve, enum label→code).
+See [docs/demo-seed.md](docs/demo-seed.md).
 `acu --completion` emits a completion script for bash, zsh, or fish — source it from your shell profile.
 Run `acu <command> --help` for details on any command.
 

{acumatica_cli-0.16.0 → acumatica_cli-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.16.0"
+version = "0.18.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 license = "PolyForm-Noncommercial-1.0.0"
 readme = "README.md"

{acumatica_cli-0.16.0 → acumatica_cli-0.18.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "acumatica-cli"
-version = "0.16.0"
+version = "0.18.0"
 description = "Acumatica ERP Config-as-Code: tenant provisioning, baseline config, and reference data"
 authors = [{ name = "Konstantin Borovik", email = "kb@lab5.ca" }]
 license = "PolyForm-Noncommercial-1.0.0"

{acumatica_cli-0.16.0 → acumatica_cli-0.18.0}/src/acumatica_cli/cli.py

@@ -1103,7 +1103,12 @@ def reconcile_cmd(
     columns land in findings files only. No REST, no SSH, no password.
     Exit 0 clean, 1 IO/parse fail; never 2 (conflicts are findings, not
     drift). Optional snapshot_map.yaml maps DAC tables to catalog
-    entities; absent → identity match on entity name.
+    entities (absent → identity match on entity name) and may declare
+    keys:/fields: seed→inv aliases, resolvers:/resolves: for FK int→CD,
+    and enums: label→code (package defaults cover Sub/UOM aliases,
+    ReasonCode/VendorClass/PostingClass/CashAccount Account+Sub,
+    ReasonCode.Usage + Account Type/Active bools, etc.). Compare always
+    pad-trims strings.
     """
     inv = (
         inventory_dir

{acumatica_cli-0.16.0 → acumatica_cli-0.18.0}/src/acumatica_cli/reconcile.py

@@ -17,6 +17,16 @@ Finding kinds (I.data findings/):
 
 Optional ``snapshot_map.yaml`` (package data or data-repo root) maps
 table → entity; absent → identity match on catalog entity name.
+
+Compare path pad-trims string keys and fields on both sides (V38) so
+fixed-width / trailing-space inventory values join and equal seed.
+Per-row optional ``keys:`` / ``fields:`` maps rename seed names →
+inventory column names (V38 M3) so e.g. SubaccountCD joins SubCD and
+UnitID joins Unit without false key-skips. Global ``resolvers:`` plus
+per-row ``resolves:`` map inv int FKs → CD strings before compare (V38 M4)
+so seed CD space matches inventory IDs (Account/Sub first). Global
+``enums:`` plus per-row ``enums:`` map REST labels → DAC codes (V38 M5)
+so e.g. Usage Adjustment vs A and Active true vs 1 do not false-delta.
 """
 
 from __future__ import annotations
@@ -91,11 +101,39 @@ class SeedFile(Model):
         return v if isinstance(v, list) else [v]
 
 
+class FkResolver(Model):
+    """Global inventory FK index: int id column → natural CD column (V38 M4)."""
+
+    table: str
+    id: str
+    cd: str
+
+    @field_validator("table", "id", "cd")
+    @classmethod
+    def _nonempty(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("resolver table/id/cd must be non-empty")
+        return v
+
+
 class TableMapEntry(Model):
-    """One optional snapshot_map row: DAC table → catalog entity."""
+    """One optional snapshot_map row: DAC table → catalog entity.
+
+    Optional ``keys`` / ``fields`` are seed-name → inventory-column aliases
+    (V38 M3). Optional ``resolves`` maps seed field → global resolver name
+    (V38 M4): inventory value is looked up id→CD before compare. Optional
+    ``enums`` maps seed field → global enum table name (V38 M5): seed labels
+    fold to DAC codes before compare. Absent aliases → identity names. v1
+    rows are ``{table, entity}`` only.
+    """
 
     table: str
     entity: str
+    keys: dict[str, str] = Field(default_factory=dict)
+    fields: dict[str, str] = Field(default_factory=dict)
+    resolves: dict[str, str] = Field(default_factory=dict)
+    enums: dict[str, str] = Field(default_factory=dict)
 
     @field_validator("table", "entity")
     @classmethod
@@ -105,17 +143,88 @@ class TableMapEntry(Model):
             raise ValueError("table/entity must be non-empty")
         return v
 
+    @field_validator("keys", "fields", "resolves", "enums", mode="before")
+    @classmethod
+    def _str_map(cls, v: object) -> object:
+        """Accept seed→inv/resolver/enum-name string maps; reject empty names."""
+        if v is None:
+            return {}
+        if not isinstance(v, dict):
+            raise ValueError("keys/fields/resolves/enums must be a mapping of strings")
+        out: dict[str, str] = {}
+        for seed_name, target in v.items():
+            s = str(seed_name).strip()
+            if isinstance(target, dict):
+                raise ValueError(
+                    f"keys/fields/resolves/enums[{s!r}]: expected string value "
+                    "(use resolves: for FK names; enums: for label->code tables)"
+                )
+            i = str(target).strip()
+            if not s or not i:
+                raise ValueError("keys/fields/resolves/enums names must be non-empty")
+            out[s] = i
+        return out
+
 
 class SnapshotMap(Model):
     """Optional table→entity map (package or data-repo ``snapshot_map.yaml``)."""
 
+    resolvers: dict[str, FkResolver] = Field(default_factory=dict)
+    enums: dict[str, dict[str, str]] = Field(default_factory=dict)
     tables: list[TableMapEntry] = Field(default_factory=list)
 
+    @field_validator("resolvers", mode="before")
+    @classmethod
+    def _resolvers_map(cls, v: object) -> object:
+        if v is None:
+            return {}
+        if not isinstance(v, dict):
+            raise ValueError("resolvers must be a mapping of name -> {table,id,cd}")
+        return v
+
+    @field_validator("enums", mode="before")
+    @classmethod
+    def _enums_map(cls, v: object) -> object:
+        """Global name → {label: code}; stringify YAML bool keys as true/false."""
+        if v is None:
+            return {}
+        if not isinstance(v, dict):
+            raise ValueError("enums must be a mapping of name -> {label: code}")
+        out: dict[str, dict[str, str]] = {}
+        for name, mapping in v.items():
+            n = str(name).strip()
+            if not n:
+                raise ValueError("enums names must be non-empty")
+            if not isinstance(mapping, dict):
+                raise ValueError(f"enums[{n!r}]: expected mapping of label -> code")
+            inner: dict[str, str] = {}
+            for label, code in mapping.items():
+                if isinstance(label, bool):
+                    lab = "true" if label else "false"
+                else:
+                    lab = str(label).strip()
+                if isinstance(code, bool):
+                    cd = "true" if code else "false"
+                else:
+                    cd = str(code).strip()
+                if not lab or not cd:
+                    raise ValueError(
+                        f"enums[{n!r}]: label/code must be non-empty strings"
+                    )
+                inner[lab] = cd
+            out[n] = inner
+        return out
+
     def entity_for(self, table: str) -> str | None:
         """Catalog entity name for a DAC table, or None when unmapped."""
+        entry = self.entry_for(table)
+        return entry.entity if entry is not None else None
+
+    def entry_for(self, table: str) -> TableMapEntry | None:
+        """Full map row for a DAC table (aliases + entity), or None."""
         for row in self.tables:
             if row.table == table:
-                return row.entity
+                return row
         return None
 
 
@@ -361,6 +470,8 @@ def reconcile(
     by_entity = _catalog_by_entity(m)
     catalog_entities = set(by_entity)
     seed_index = _index_seeds(seeds)
+    fk_indexes = _build_fk_indexes(inv, smap.resolvers)
+    enum_tables = smap.enums
     config_present = config_dir is not None and config_dir.is_dir()
 
     unmapped: list[UnmappedTable] = []
@@ -387,6 +498,7 @@ def reconcile(
                 seeds=seed_index,
             )
         )
+        map_entry = smap.entry_for(table.name)
         deltas.extend(
             _deltas_for_table(
                 entity=entity,
@@ -394,6 +506,9 @@ def reconcile(
                 specs=specs,
                 config_present=config_present,
                 seeds=seed_index,
+                map_entry=map_entry,
+                fk_indexes=fk_indexes,
+                enum_tables=enum_tables,
             )
         )
         _append_usr_custom(custom, table.name, entity, col_names)
@@ -484,16 +599,22 @@ def _rest_gaps_for_table(
     return gaps
 
 
-def _deltas_for_table(
+def _deltas_for_table(  # noqa: PLR0913 — keyword-only; map + V38 indexes
     *,
     entity: str,
     table: inventory.TableData,
     specs: list[extract.EntitySpec],
     config_present: bool,
     seeds: _SeedIndex,
+    map_entry: TableMapEntry | None = None,
+    fk_indexes: dict[str, dict[str, str]] | None = None,
+    enum_tables: dict[str, dict[str, str]] | None = None,
 ) -> list[FieldDelta]:
+    """Per-spec field deltas for one inventory table (optional map aliases)."""
     if not config_present:
         return []
+    indexes = fk_indexes if fk_indexes is not None else {}
+    enums = enum_tables if enum_tables is not None else {}
     out: list[FieldDelta] = []
     for spec in specs:
         seed_file = _find_seed_for_spec(spec, seeds)
@@ -501,7 +622,13 @@ def _deltas_for_table(
             continue
         out.extend(
             _compare_seed_table(
-                entity=entity, table=table, seed_file=seed_file, spec=spec
+                entity=entity,
+                table=table,
+                seed_file=seed_file,
+                spec=spec,
+                map_entry=map_entry,
+                fk_indexes=indexes,
+                enum_tables=enums,
             )
         )
     return out
@@ -537,37 +664,137 @@ def _find_seed_for_spec(spec: extract.EntitySpec, seeds: _SeedIndex) -> SeedFile
     return None
 
 
-def _compare_seed_table(
+def _build_fk_indexes(
+    inv: InventoryTree, resolvers: dict[str, FkResolver]
+) -> dict[str, dict[str, str]]:
+    """Build resolver_name → {id_norm: cd_norm} from inventory tables (V38 M4)."""
+    indexes: dict[str, dict[str, str]] = {}
+    by_name = inv.by_name
+    for name, spec in resolvers.items():
+        table = by_name.get(spec.table)
+        if table is None:
+            indexes[name] = {}
+            continue
+        idx: dict[str, str] = {}
+        for row in table.rows:
+            if spec.id not in row or spec.cd not in row:
+                continue
+            idx[_norm(row[spec.id])] = _norm(row[spec.cd])
+        indexes[name] = idx
+    return indexes
+
+
+def _resolve_inv_value(
+    raw: str,
+    *,
+    field: str,
+    resolves: dict[str, str],
+    fk_indexes: dict[str, dict[str, str]],
+) -> str:
+    """Map inventory FK id → CD when field has a resolver; else return raw."""
+    resolver_name = resolves.get(field)
+    if resolver_name is None:
+        return raw
+    id_to_cd = fk_indexes.get(resolver_name)
+    if not id_to_cd:
+        return raw
+    return id_to_cd.get(raw, raw)
+
+
+def _enum_norm(
+    raw: str,
+    *,
+    field: str,
+    field_enums: dict[str, str],
+    enum_tables: dict[str, dict[str, str]],
+) -> str:
+    """Map REST label → DAC code when field has an enum table (V38 M5).
+
+    Seed side usually carries labels (Adjustment, Asset, true); inventory
+    stores codes (A, A, 1). Labels in the table fold to codes; values that
+    already equal a code (or are unmapped) pass through unchanged.
+    """
+    enum_name = field_enums.get(field)
+    if enum_name is None:
+        return raw
+    table = enum_tables.get(enum_name)
+    if not table:
+        return raw
+    if raw in table:
+        return table[raw]
+    # case-insensitive label match (seed YAML sometimes differs in case)
+    lower = raw.lower()
+    for lab, code in table.items():
+        if lab.lower() == lower:
+            return code
+    return raw
+
+
+def _compare_seed_table(  # noqa: PLR0913 — keyword-only compare bundle
     *,
     entity: str,
     table: inventory.TableData,
     seed_file: SeedFile,
     spec: extract.EntitySpec,
+    map_entry: TableMapEntry | None = None,
+    fk_indexes: dict[str, dict[str, str]] | None = None,
+    enum_tables: dict[str, dict[str, str]] | None = None,
 ) -> list[FieldDelta]:
     """Field-level compare for rows that share a key tuple on both sides.
 
     Key fields come from the seed file (authoritative for CaC). Inventory
     column names often match contract field names; missing inventory key
-    → skip that seed row (no false delta). Values compared as stripped
-    strings. Detail lists skipped (not comparable to flat snapshot rows).
+    → skip that seed row (no false delta). Optional map ``keys`` / ``fields``
+    rename seed names → inv columns (V38 M3). Optional ``resolves`` + global
+    FK indexes convert inv int IDs → CD before compare (V38 M4; prefer seed
+    CD space). Optional ``enums`` + global enum tables fold seed labels →
+    codes (V38 M5). Join keys and field values are pad-trimmed on both sides
+    (V38) so fixed-width / trailing-space DAC columns match seed natural keys.
+    Detail lists skipped (not comparable to flat snapshot rows). Findings
+    always report seed-side field names and resolved inventory values.
     """
     keys = seed_file.keys
-    inv_index = _index_inventory_rows(table.rows, keys)
+    key_alias = map_entry.keys if map_entry is not None else {}
+    field_alias = map_entry.fields if map_entry is not None else {}
+    resolves = map_entry.resolves if map_entry is not None else {}
+    field_enums = map_entry.enums if map_entry is not None else {}
+    indexes = fk_indexes if fk_indexes is not None else {}
+    enums = enum_tables if enum_tables is not None else {}
+    inv_keys = [key_alias.get(k, k) for k in keys]
+    inv_index = _index_inventory_rows(table.rows, inv_keys)
     deltas: list[FieldDelta] = []
     for rec in seed_file.records:
         if not all(k in rec for k in keys):
             continue
-        ident = tuple(str(rec[k]) for k in keys)
+        # V38: pad-trim key identity both sides so join is padding-invariant.
+        # Seed values are looked up under inv column names (alias or identity).
+        ident = tuple(_norm(rec[k]) for k in keys)
         inv_row = inv_index.get(ident)
         if inv_row is None:
             continue
         for field, seed_val in sorted(rec.items()):
             if field in keys or isinstance(seed_val, (list, dict)):
                 continue
-            if field not in inv_row:
+            inv_field = field_alias.get(field, field)
+            if inv_field not in inv_row:
                 continue
-            left = _norm(seed_val)
-            right = _norm(inv_row[field])
+            left = _enum_norm(
+                _norm(seed_val),
+                field=field,
+                field_enums=field_enums,
+                enum_tables=enums,
+            )
+            right = _enum_norm(
+                _resolve_inv_value(
+                    _norm(inv_row[inv_field]),
+                    field=field,
+                    resolves=resolves,
+                    fk_indexes=indexes,
+                ),
+                field=field,
+                field_enums=field_enums,
+                enum_tables=enums,
+            )
             if left != right:
                 deltas.append(
                     FieldDelta(
@@ -586,27 +813,48 @@ def _compare_seed_table(
 def _index_inventory_rows(
     rows: list[dict[str, str]], keys: list[str]
 ) -> dict[tuple[str, ...], dict[str, str]]:
+    """Index inventory rows by pad-trimmed key tuple (V38 join).
+
+    ``keys`` are inventory column names (after seed→inv alias resolution).
+    """
     inv_index: dict[tuple[str, ...], dict[str, str]] = {}
     for row in rows:
         if all(k in row for k in keys):
-            inv_index[tuple(str(row[k]) for k in keys)] = row
+            inv_index[tuple(_norm(row[k]) for k in keys)] = row
     return inv_index
 
 
 def _norm(value: Any) -> str:
-    """Comparable string form (bool/number/string), sibling of seed._norm spirit."""
+    """Pad-trim comparable form for join keys and field values (V38).
+
+    String sides strip leading/trailing whitespace (DAC/NVarChar padding).
+    Bools/numbers fold to a stable spelling so seed and inventory agree.
+    Decimal-looking strings with a point collapse trailing zeros so seed
+    ``0`` matches inventory ``0.000000`` without treating bare CDs like
+    ``000000`` as numbers. Sibling of ``seed._norm`` spirit; used on *both*
+    key join and field compare so padded inventory never misses a seed row
+    or false-deltas.
+    """
     if isinstance(value, bool):
-        return "true" if value else "false"
-    if value is None:
-        return ""
-    if isinstance(value, int) and not isinstance(value, bool):
-        return str(value)
-    if isinstance(value, float):
+        s = "true" if value else "false"
+    elif value is None:
+        s = ""
+    elif isinstance(value, int):
+        s = str(value)
+    elif isinstance(value, float):
         as_int = int(value)
-        if value == float(as_int):
-            return str(as_int)
-        return str(value)
-    return str(value).strip()
+        s = str(as_int) if value == float(as_int) else str(value)
+    else:
+        s = str(value).strip()
+        if "." in s:
+            try:
+                f = float(s)
+            except ValueError:
+                return s
+            as_int = int(f)
+            if f == float(as_int):
+                s = str(as_int)
+    return s
 
 
 # ---------------------------------------------------------------------------

acumatica_cli-0.18.0/src/acumatica_cli/snapshot_map.yaml

@@ -0,0 +1,167 @@
+# snapshot_map.yaml — package defaults for `acu reconcile` (V38)
+#
+# table → catalog entity. Optional keys:/fields: rename seed names →
+# inventory columns so join/compare works when DAC names differ (M3).
+# Global resolvers: + per-row resolves: map inv int FKs → CD (M4).
+# Global enums: + per-row enums: map REST labels → DAC codes (M5).
+# Data-repo root snapshot_map.yaml wins over this package file.
+# v1 rows remain {table, entity} only — aliases/resolves/enums optional.
+
+resolvers:
+  account_cd:
+    table: Account
+    id: AccountID
+    cd: AccountCD
+  sub_cd:
+    table: Sub
+    id: SubID
+    cd: SubCD
+  branch_cd:
+    table: Branch
+    id: BranchID
+    cd: BranchCD
+
+enums:
+  reason_usage:
+    Adjustment: A
+    Assembly/Disassembly: D
+    Issue: I
+    Receipt: R
+    Vendor Return: N
+  account_type:
+    Asset: A
+    Liability: L
+    Income: I
+    Expense: E
+  post_option:
+    Summary: S
+    Detail: D
+  due_type:
+    Fixed Number of Days: N
+  disc_type:
+    Fixed Number of Days: N
+  visible_to:
+    All: AL
+  prepare_on:
+    Fixed Day of Month: F
+  bool_bit:
+    "true": "1"
+    "false": "0"
+
+tables:
+  # Wave 1 renames — key/field aliases where seed ≠ DAC column
+  - table: Sub
+    entity: Subaccount
+    keys:
+      SubaccountCD: SubCD
+    enums:
+      Active: bool_bit
+  - table: Terms
+    entity: CreditTerms
+    enums:
+      DueType: due_type
+      DiscType: disc_type
+      VisibleTo: visible_to
+  - table: UnitOfMeasure
+    entity: UnitsOfMeasure
+    keys:
+      UnitID: Unit
+    fields:
+      Description: Descr
+  - table: INAvailabilityScheme
+    entity: AvailabilityCalculationRule
+  - table: SOSetup
+    entity: SOPreferences
+    enums:
+      AutoReleaseIN: bool_bit
+      HoldShipments: bool_bit
+      RequireShipmentTotal: bool_bit
+  - table: POSetup
+    entity: POPreferences
+  - table: ARSetup
+    entity: ARPreferences
+  - table: APSetup
+    entity: APPreferences
+
+  # Wave 2 — table renames + PostingClass FK resolve
+  - table: INPostClass
+    entity: PostingClass
+    resolves:
+      COGSAcctID: account_cd
+      COGSSubID: sub_cd
+      InvtAcctID: account_cd
+      InvtSubID: sub_cd
+      LCVarianceAcctID: account_cd
+      LCVarianceSubID: sub_cd
+      POAccrualAcctID: account_cd
+      POAccrualSubID: sub_cd
+      PPVAcctID: account_cd
+      PPVSubID: sub_cd
+      SalesAcctID: account_cd
+      SalesSubID: sub_cd
+  - table: INItemClass
+    entity: ItemClass
+  - table: INSite
+    entity: Warehouse
+    enums:
+      Active: bool_bit
+  - table: InventoryItem
+    entity: StockItem
+  - table: INSetup
+    entity: INPreferences
+  - table: CASetup
+    entity: CAPreferences
+  - table: GLSetup
+    entity: GLPreferences
+
+  # Wave 3
+  - table: INKitSpecHdr
+    entity: KitSpecification
+  - table: SOOrderType
+    entity: OrderType
+    resolves:
+      FreightAcctID: account_cd
+      FreightSubID: sub_cd
+    enums:
+      Active: bool_bit
+  - table: ARStatementCycle
+    entity: StatementCycle
+    enums:
+      PrepareOn: prepare_on
+  - table: OrganizationLedgerLink
+    entity: LedgerCompany
+
+  # Identity tables — FK resolve (M4) + enums (M5)
+  - table: Account
+    entity: Account
+    enums:
+      Type: account_type
+      PostOption: post_option
+      Active: bool_bit
+      RequireUnits: bool_bit
+  - table: ReasonCode
+    entity: ReasonCode
+    resolves:
+      AccountID: account_cd
+      SubID: sub_cd
+    enums:
+      Usage: reason_usage
+  - table: VendorClass
+    entity: VendorClass
+    resolves:
+      APAcctID: account_cd
+      APSubID: sub_cd
+      DiscTakenAcctID: account_cd
+      DiscTakenSubID: sub_cd
+      ExpenseAcctID: account_cd
+      ExpenseSubID: sub_cd
+      POAccrualAcctID: account_cd
+      POAccrualSubID: sub_cd
+  - table: CashAccount
+    entity: CashAccount
+    resolves:
+      AccountID: account_cd
+      SubID: sub_cd
+      BranchID: branch_cd
+    enums:
+      Active: bool_bit