Component Wiring Check

Component Wiring Check

Audit cross-component reference contracts on a Datex Studio branch — verify that one component's reference to another (a hub tab mounting a grid, a hub filter pointing at a selector, a grid's datasourceConfig pointing at a datasource, a selector backed by a datasource, a form opened via $shell.<Package>.open<referenceName>Dialog) is contract-complete. This is a read-only audit skill: it reads configs, reports findings, and routes fixes to the matching creator skill. It never mutates configs on the branch.

See also: the creator skills (hub-creator, grid-creator, form-creator, editor-creator, selector-creator) — each owns the round-trip + push step for fixes the audit surfaces.

References

• ../datex-studio-shared/branch-setup.md — Branch/connection selection (shared across skills)
• references/component-wiring.md — Authoritative wiring-rule reference: the three silent-failure traps, moduleId rule, configParameters ↔ inParams mirror, vars / rowVars declaration rule
• ../datex-studio-conventions/defaults.md — Default package for new components (not for references to existing ones — important not to confuse the two)
• ../tailoring-overlay/ — Overlay-specific shadow-marker rules (the "outdated contract at import" symptom is a separate tailoring concern)

Dependencies

• grid-creator / hub-creator / form-creator / editor-creator / selector-creator skills — invoked downstream when this audit surfaces a fix to apply (this skill reports findings; the creator skill carries the round-trip + push)
• tailoring-overlay skill — invoked when the symptom is "outdated contract" on a tailored overlay rather than a wiring drift on the base component
• post-edit-verification / component-validator skills — invoked after fixes land, by the creator skill that applied them (not by this audit directly)

CLI Lifecycle

Component-wiring audits are read-only — they fetch configs and inspect contracts, but they never push changes. There is no dxs componentwiringcheck subcommand; the audit uses the generic dxs configuration get / list primitives to pull the components it needs to compare.

Fetch a single component for inspection:

# 1. Fetch — note the envelope wrapper
dxs configuration get <type> <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (same envelope-vs-body distinction as the creator skills)
jq .json envelope.json > body.json
# 3. Inspect — read inParams, configParameters, moduleId, vars, rowVars

Discover candidates on the branch:

# List configs of a given type — filter to the components you want to audit
dxs configuration list <type> -b <branchId>

Fixes the audit surfaces are applied by the matching creator skill (hub-creator, grid-creator, etc.), which owns the round-trip rule (get -O envelope.json → jq .json → edit → upsert). This skill does not call dxs configuration upsert — if you find yourself reaching for it, hand off to the creator skill instead.

Workflow

[Phase 1: Setup + target components]
Follow branch-setup.md for branch/connection selection
        |
Identify the reference under audit:
  - referencing component (the caller — hub, grid, form, ...)
  - target component (the callee — grid, selector, datasource, form, ...)
  - the reference site (hub filter, hub tab, grid datasourceConfig,
    selector datasource, dialog opener)
        |
[Phase 2: Audit reference contracts]
Walk the three silent-failure traps (see references/component-wiring.md):
  1. moduleId matches the target's package?
  2. configParameters mirrors target inParams one-to-one
     (no missing, no extras)?
  3. vars / rowVars declares every $<component>.vars.<id> /
     $row.vars.<id> used in flow code?
Cross-check tailored overlays separately (see tailoring-overlay)
        |
[Phase 3: Report findings]
For each trap that fires, surface:
  - what's broken (target id / inParam / var)
  - which component file owns the fix (caller vs callee)
  - which creator skill applies it
NO `dxs configuration upsert` from this skill — defer to the
creator skill that owns the component being edited
        |
[Phase 4: Re-audit (optional, after fixes land)]
Re-fetch the same configs and walk the three traps again.
Clean run = no findings.

Phase Details

Phase 1: Setup + target components

1. Follow ../datex-studio-shared/branch-setup.md for branch and connection selection. Never assume a branch ID — ask the user to confirm.
2. Identify the reference site. A wiring audit is always about a specific pair (or chain) of components. Establish:
   • Referencing component (the caller): the hub that mounts a grid, the grid whose datasourceConfig points at a datasource, the selector whose datasource backs the dropdown, the action that opens a form via $shell.<Package>.open<referenceName>Dialog(...).
   • Target component (the callee): the grid, selector, datasource, form, or editor on the receiving end of the reference.
   • Reference site: hub filter (→ selector), hub tab contentConfig (→ grid or other component), grid datasourceConfig (→ datasource), selector datasourceConfig (→ datasource), action-tier dialog opener (→ form/editor).
3. Fetch both components with dxs configuration get <type> <configId> -b <branchId> -O envelope.json and extract body.json via jq .json for each. The audit reads the bodies; no edits flow from this skill.

Phase 2: Audit reference contracts

Walk the three traps in order. Each is fully specified in references/component-wiring.md; the summary below is the audit checklist.

1. moduleId matches the target's package. On every reference site, the moduleId field is the package the target lives in — not the caller's package, not the feature folder name. Open the target component file's package declaration directly (or ask the user if it isn't obvious). Do not infer from feature folder names or from the Utilities default for new components — that default applies to new components, not to references to existing ones. See references/component-wiring.md → Cross-Component References Use the Target's Module.

2. configParameters mirrors target inParams one-to-one. Diff the two arrays:

   • For each entry in the target's inParams, confirm configParameters on the reference has a matching entry (same id / type / isCollection). Unused params stay in the contract with explicit value: null / "". Missing entries silently surface as undefined inputs at runtime — empty dropdowns, misfiltered lists.
   • For each entry in configParameters, confirm the target's inParams declares that id. Extra entries are dead wiring — the value is silently dropped, the caller thinks data is flowing through, the target never sees it. This is the more dangerous direction. The rule applies regardless of required: true/false on the target inParam.

   When the target's shape doesn't match what the caller needs (e.g. a hub wants to scope a grid by project_ids but the grid doesn't declare that inParam yet), extend the target rather than adding phantom entries to the caller. See references/component-wiring.md → Reference Contracts Include Every Target inParam.

3. Vars / rowVars declared. For each $<component>.vars.<id> ($form.vars, $hub.vars, $editor.vars, $grid.vars) read or written in flow code, confirm a matching entry exists in the component's top-level vars[] array. For grids, additionally confirm every $row.vars.<id> used inside row flows (on_save_new_row, on_save_existing_row, etc.) has a matching entry in the grid's rowVars[]. Both arrays use the inParam-shaped descriptor. See references/component-wiring.md → Component Variables Must Be Declared.

4. Tailored overlays are a separate concern. If the symptom is "outdated contract at import" rather than runtime drift, the cause is shadow-marker drift on a tailored overlay, not a wiring drift on the base component. Hand off to the tailoring-overlay skill.

Phase 3: Report findings

For each trap that fires, write up a finding that pairs the broken contract with the fix-owner:

This skill does not push fixes. Surface the findings, point at the creator skill that owns each fix, and stop. The creator skill carries the round-trip rule (dxs configuration get -O envelope.json → jq .json envelope.json > body.json → edit → dxs configuration upsert); applying fixes from inside the audit skill bypasses that contract and risks silently destroying configuration content.

Phase 4: Re-audit (optional)

After fixes land, re-fetch the same components (dxs configuration get <type> <configId> -b <branchId> -O envelope.json, extract via jq .json) and walk the three traps a second time. A clean run = no findings. Re-audit is cheap; do it whenever a fix touches more than one component file or when the original audit surfaced more than two findings — drift can recur in the same edit if the caller and target weren't updated atomically.

Silent-Failure Symptoms — Diagnostic Index

When a user reports a symptom rather than a known broken contract, this table maps the symptom back to the trap to audit first. See references/component-wiring.md for the underlying mechanics.

Pre-Flight Checklist

Walk this when auditing a cross-component reference. The full checklist lives in references/component-wiring.md; the fast version:

1. moduleId matches the target's package — confirmed by reading the target component file or asking the user. Not inferred from the feature folder or the Utilities new-component default.
2. configParameters is a one-to-one match against the target's inParams — every inParam has an entry (unused ones with value: null / ""); no extra entries.
3. If the target is out of sync with what the caller needs, the fix extends the target in the same edit rather than adding phantom entries to the caller. The caller's configParameters must only ever describe what the target actually accepts.
4. Every $<component>.vars.<id> written in flow code is declared in the component's top-level vars[] array.
5. Grid rowVars[] declares every $row.vars.<id> read or written by row flows.
6. Dialog openers use the target form's package — $shell.<TargetPackage>.open<referenceName>Dialog(...), with <referenceName> in snake_case (no camelCasing).

Common Mistakes

After your audit produces findings, route each finding to the matching creator skill (grid-creator, hub-creator, etc.) to apply the fix. Re-invoke this skill after fixes land for a clean-run verification.