feature:xray

Inspect a feature’s extension points, template hook registrations, and refinement map. Shows what a feature exposes, what it fills, and what has been overridden by refinement features.

Usage
Options
Examples
Product layout hooks
Feature extension points
Refinement map
Validation
1. Checks performed
2. Example output
Description
See also

Usage

splent feature:xray [FEATURE] [--services] [--templates] [--models] [--routes] [--hooks] [--commands] [--signals] [--validate]

When called without a FEATURE argument, inspects all features in the active product. When called with a feature name, inspects only that feature.

When called without any filter flags, all sections are shown. Use flags to narrow the output.

Options

Option	Description
`--services`	Show service classes and any overrides
`--templates`	Show template files and any overrides
`--models`	Show model classes and any extensions
`--routes`	Show registered routes
`--hooks`	Show template hook registrations and slot assignments
`--commands`	Show CLI commands contributed by the feature
`--signals`	Show signals emitted by the feature
`--validate`	Run validation checks to detect collisions and conflicts

Examples

splent feature:xray                           # All features, all sections
splent feature:xray splent_feature_auth       # Single feature, all sections
splent feature:xray --hooks                   # All features, hooks only
splent feature:xray --commands                # All features, commands only
splent feature:xray --signals                 # All features, signals only
splent feature:xray splent_feature_auth --services --models
splent feature:xray --validate                # Run all validation checks

Product layout hooks

When --hooks is active (or no flags are given), the output includes a layout hook map showing which feature fills each slot in the product’s base_template.html:

  Product layout hooks
  ────────────────────────────────────────────────────────────
  Slot                              Feature
  ────────────────────────────────────────────────────────────
  layout.head                       splent_feature_public
  layout.nav_start                  splent_feature_public
  layout.nav_end                    splent_feature_auth
  layout.anonymous_sidebar          splent_feature_auth
  layout.authenticated_sidebar      splent_feature_auth
                                    splent_feature_profile
  layout.footer                     splent_feature_public
  layout.scripts                    splent_feature_auth
  layout.modals                     (empty)

Multiple features can contribute to the same slot — they are listed in load order.

Feature extension points

For each feature, shows what it declares as extensible in [tool.splent.contract.extensible]:

  Extension points — splent_feature_auth
  ────────────────────────────────────────────────────────────
  Type          Name                        Extensible
  ────────────────────────────────────────────────────────────
  service       AuthenticationService        yes
  model         User                         yes (columns, relationships)
  template      auth/login_form.html         yes
  hook          layout.anonymous_sidebar     yes

Shows what has been overridden by refinement features:

  Refinement map
  ────────────────────────────────────────────────────────────
  Base feature        Type       Name                      Refined by
  ────────────────────────────────────────────────────────────
  auth                service    AuthenticationService      premium_auth
  auth                template   auth/login_form.html       premium_auth
  auth                hook       layout.anonymous_sidebar   premium_auth

This is the runtime view of the RefinementRegistry — it shows exactly what is overridden and by whom.

Validation

The --validate flag runs a series of checks across all features in the product to detect collisions, conflicts, and misconfigured extension points. It exits with code 1 if any issue is found.

splent feature:xray --validate

Checks performed

#	Check	Severity	Description
1	Services	error	Detects service name collisions. Legitimate refinement overrides are recognized and reported as OK.
2	Models	error	Detects model name collisions across features.
3	Routes	error	Detects route path collisions across features.
4	Blueprints	error	Detects blueprint name collisions across features.
5	Commands	error	Detects CLI command name collisions across features.
6	Signals	error	Detects signal name collisions (two features emitting the same signal).
7	Hooks	info	Reports shared hook slots (multiple features contributing to the same slot). This is informational — hooks are additive by design.
8	Layout hooks	info	Reports unused hook slots declared in the product layout.
9	Refinement targets	error	Validates that every refinement override targets a point declared as extensible by the base feature.

Example output

  ── Validation ──

  ✅ Services: no collisions (4 unique)
  ✅ Models: no collisions (3 unique)
  ✅ Routes: no collisions (8 unique)
  ✅ Blueprints: no collisions (5 unique)
  ✅ Commands: no collisions (2 unique)
  ✅ Signals: no collisions (3 unique)
  ℹ️  Hook 'layout.scripts' — 2 contributors: splent_feature_auth, splent_feature_public
  ✅ Hooks: 1 shared slot(s) — additive, OK
  ✅ Layout: 5/6 hooks active
  ✅ premium_auth overrides auth/AuthenticationService — allowed

  ✅ All 9 checks passed.

Description

feature:xray reads the feature contract ([tool.splent.contract] in pyproject.toml) — including services, models, routes, hooks, commands, and signals — and the runtime RefinementRegistry to produce a complete picture of a feature’s integration surface.

It is useful for:

Understanding which slots in the product layout are filled and by whom
Verifying that a refinement feature is correctly overriding its target
Auditing the extension surface before releasing a feature
Debugging template or service resolution issues
Detecting collisions across features (services, models, routes, blueprints, commands, signals) via --validate