Skip to content

refactor(compositor): rename input namespace to compositor #135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
K1ngst0m merged 1 commit into from
Mar 19, 2026
Merged

refactor(compositor): rename input namespace to compositor #135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions openspec/changes/archive/2026-03-19-rename-compositor-namespace/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Design: Rename compositor namespace from goggles::input to goggles::compositor

## Technical Approach

This is a mechanical find-and-replace rename executed as a single atomic commit. Every occurrence of `namespace goggles::input` and every qualified `goggles::input::` reference is replaced with `goggles::compositor`. No phased rollout, no compatibility shims, no intermediate states.

The change touches three categories of files:

1. **Compositor source** (14 files): Replace `namespace goggles::input` declarations in all headers and implementation files under `src/compositor/`.
2. **UI forward declaration** (1 file): Update the forward declaration of `SurfaceInfo` in `src/ui/imgui_layer.hpp`.
3. **Test references** (3 files): Update qualified `goggles::input::` references in `tests/input/` and `tests/render/`.

Total: 18 files modified, 0 files created or deleted.

## Architecture Decisions

### Decision: Single atomic commit

**Choice**: Apply all 18 file changes in one commit.
**Alternatives considered**: Incremental migration with a namespace alias bridging old and new names across multiple commits.
**Rationale**: The rename is purely mechanical with no external consumers or ABI boundary. A single commit eliminates any intermediate state where both namespaces coexist. If the build breaks, the failure is a hard compile error (the old namespace ceases to exist), making missed references trivially detectable. Rollback is a single `git revert`.

### Decision: Type names unchanged

**Choice**: Keep all type names as-is (e.g., `InputEventType`, `CompositorServer`).
**Alternatives considered**: Rename types that contain "input" to use "compositor" for consistency.
**Rationale**: Type names like `InputEventType` are semantic names describing what they represent (input events), not artifacts of the namespace they happen to live in. Renaming them would be a separate semantic change with its own scope and risk, not part of a namespace alignment fix.

### Decision: Archived openspec documents not updated

**Choice**: Do not modify any existing openspec documents that reference `goggles::input`.
**Alternatives considered**: Update all historical references across the repository.
**Rationale**: Archived design documents are historical records. Retroactively editing them misrepresents what was designed at the time. The rename is self-documenting through this change's own openspec artifacts and the git history.

## Affected Components

### Compositor source files (14 files)

All files under `src/compositor/` that declare `namespace goggles::input`:

| File | Type |
|------|------|
| `src/compositor/compositor_server.hpp` | Public header |
| `src/compositor/compositor_server.cpp` | Implementation |
| `src/compositor/compositor_state.hpp` | Internal header |
| `src/compositor/compositor_protocol_hooks.hpp` | Internal header |
| `src/compositor/compositor_targets.hpp` | Internal header |
| `src/compositor/compositor_runtime_metrics.hpp` | Internal header |
| `src/compositor/compositor_core.cpp` | Implementation |
| `src/compositor/compositor_cursor.cpp` | Implementation |
| `src/compositor/compositor_input.cpp` | Implementation |
| `src/compositor/compositor_focus.cpp` | Implementation |
| `src/compositor/compositor_layer_shell.cpp` | Implementation |
| `src/compositor/compositor_present.cpp` | Implementation |
| `src/compositor/compositor_xdg.cpp` | Implementation |
| `src/compositor/compositor_xwayland.cpp` | Implementation |

### UI forward declaration (1 file)

| File | Change |
|------|--------|
| `src/ui/imgui_layer.hpp` | `namespace goggles::input { struct SurfaceInfo; }` becomes `namespace goggles::compositor { struct SurfaceInfo; }` |

### Test references (3 files)

| File | Symbols referenced |
|------|-------------------|
| `tests/input/auto_input_forwarding_wayland.cpp` | `goggles::input::CompositorServer::create()` |
| `tests/input/auto_input_forwarding_x11.cpp` | `goggles::input::CompositorServer::create()` |
| `tests/render/test_filter_boundary_contracts.cpp` | `goggles::input::wlr_surface*`, `goggles::input::RuntimeMetricsState` |

### Unaffected areas

| Area | Why unaffected |
|------|---------------|
| `filter-chain/` | Zero references to `goggles::input` anywhere in the submodule |
| CMake build files | No namespace-dependent configuration exists |
| `shaders/retroarch/` | Read-only upstream mirror, no C++ references |
| `research/` | Read-only reference material |

## Data Flow

No data flow changes. The rename is purely syntactic. All runtime behavior, call graphs, data ownership, threading model, and module boundaries remain identical. The compiled binary is semantically equivalent (only symbol mangling changes, which is irrelevant since there is no binary distribution or ABI stability contract).

## Interfaces / Contracts

No interface or contract changes. Every public and internal API retains its signature, semantics, and behavior. The only difference is the enclosing namespace identifier in declarations and qualified references.

## Testing Strategy

| Layer | What to Test | Approach |
|-------|--------------|----------|
| Compilation | All 18 modified files compile | `pixi run build -p debug` confirms no remaining `goggles::input` references cause errors |
| Unit + integration tests | All existing tests pass | `pixi run test -p test` exercises the full test suite including the 3 modified test files |
| Full CI | Format, ASAN, clang-tidy, consumer validation, semgrep | `pixi run ci --runner container --cache-mode warm --lane all` is the single acceptance gate |

No new tests are needed. The rename does not introduce new behavior to verify. The existing test suite provides complete coverage of the renamed namespace through the 3 test files that reference compositor types.

## Verification Strategy

1. `pixi run format` — ensure clang-format compliance after edits.
2. `pixi run ci --runner container --cache-mode warm --lane all` — full CI pipeline as the sole acceptance gate per project policy (ALWAYS rule I2/I7).

A green full-CI run is the only accepted verification. Partial commands are useful during development but do not substitute for the final gate.

## Migration / Rollout

Not applicable. This is a single atomic commit with no migration path, no compatibility period, and no phased rollout. The old namespace ceases to exist the moment the commit lands.

**Rollback**: `git revert <commit-sha>` restores `goggles::input` everywhere.

## Open Questions

None. All decisions are resolved in the proposal. The rename is fully mechanical with no ambiguity.
133 changes: 133 additions & 0 deletions openspec/changes/archive/2026-03-19-rename-compositor-namespace/proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Proposal: Rename compositor namespace from goggles::input to goggles::compositor

## Problem

The compositor module (`src/compositor/`) uses `goggles::input` as its C++ namespace. Every other module follows the project convention that namespace matches directory name (`app` → `goggles::app`, `render` → `goggles::render`, `ui` → `goggles::ui`, `util` → `goggles::util`). The compositor is the sole exception, affecting 14 source files internally and 4 files externally. This violates the ALWAYS rule "Follow namespace convention: `goggles::{module_name}`" (PROJECT_RULES.md, I3) and was confirmed as a historical anomaly in RFC.md (I5, Q1 — resolved: rename).

## Intent

Rename the `goggles::input` namespace to `goggles::compositor` so the project-wide namespace convention holds uniformly with zero exceptions.

## Scope

### In Scope

- Rename all `namespace goggles::input` declarations in `src/compositor/` to `namespace goggles::compositor`.
- Update all qualified references (`goggles::input::*`) in consuming modules and tests.
- Update the forward declaration in `src/ui/imgui_layer.hpp`.
- Run `pixi run format` after changes.
- Verify with `pixi run ci --runner container --cache-mode warm --lane all`.

### Out of Scope

- Renaming or reorganizing the `src/compositor/` directory structure.
- Changing any type names, function signatures, or class APIs within the compositor module.
- Modifying the filter-chain submodule (confirmed: zero references to `goggles::input`).
- Updating archived openspec documents (historical records remain as-is).
- Any functional or behavioral changes to the compositor.

## Approach

This is a single-phase mechanical rename. No architectural changes, no phased rollout.

### Step 1: Namespace declarations (14 files)

Replace `namespace goggles::input` with `namespace goggles::compositor` in all compositor module files:

| File | Type |
|------|------|
| `src/compositor/compositor_server.hpp` | Public header |
| `src/compositor/compositor_server.cpp` | Implementation |
| `src/compositor/compositor_state.hpp` | Internal header |
| `src/compositor/compositor_protocol_hooks.hpp` | Internal header |
| `src/compositor/compositor_targets.hpp` | Internal header |
| `src/compositor/compositor_runtime_metrics.hpp` | Internal header |
| `src/compositor/compositor_core.cpp` | Implementation |
| `src/compositor/compositor_cursor.cpp` | Implementation |
| `src/compositor/compositor_input.cpp` | Implementation |
| `src/compositor/compositor_focus.cpp` | Implementation |
| `src/compositor/compositor_layer_shell.cpp` | Implementation |
| `src/compositor/compositor_present.cpp` | Implementation |
| `src/compositor/compositor_xdg.cpp` | Implementation |
| `src/compositor/compositor_xwayland.cpp` | Implementation |

### Step 2: Forward declaration (1 file)

Update `src/ui/imgui_layer.hpp`:
- `namespace goggles::input { struct SurfaceInfo; }` → `namespace goggles::compositor { struct SurfaceInfo; }`

### Step 3: Qualified references in tests (3 files)

Update all `goggles::input::` qualifications:

| File | Symbols referenced |
|------|-------------------|
| `tests/input/auto_input_forwarding_wayland.cpp` | `goggles::input::CompositorServer::create()` |
| `tests/input/auto_input_forwarding_x11.cpp` | `goggles::input::CompositorServer::create()` |
| `tests/render/test_filter_boundary_contracts.cpp` | `goggles::input::wlr_surface*`, `goggles::input::RuntimeMetricsState` |

### Step 4: Format and verify

1. `pixi run format`
2. `pixi run ci --runner container --cache-mode warm --lane all`

## Affected Areas

| Area | Impact | Description |
|------|--------|-------------|
| `src/compositor/*.hpp` | Modified | Namespace declaration changed in 6 headers |
| `src/compositor/*.cpp` | Modified | Namespace declaration changed in 8 implementation files |
| `src/ui/imgui_layer.hpp` | Modified | Forward declaration updated |
| `tests/input/auto_input_forwarding_*.cpp` | Modified | Qualified name references updated (2 files) |
| `tests/render/test_filter_boundary_contracts.cpp` | Modified | Qualified name references updated |
| `filter-chain/` | None | Zero references to `goggles::input` — no changes needed |
| CMake build files | None | No namespace-dependent configuration exists |

**Total: 18 files modified, 0 files created or deleted.**

## Non-goals

- Introduce a new `compositor` sub-namespace hierarchy or reorganize types within the module.
- Rename or split any types (e.g., keeping `InputEventType` as-is — the type name is semantic, not a namespace artifact).
- Update archived design documents that reference the old namespace.

## Risks

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| Missed reference causes build failure | Low | Full CI gate catches all compile errors; `goggles::input` does not exist after rename, so any remaining reference is a hard compile error |
| Symbol mangling change breaks something | None | Monolithic build; no binary distribution or ABI stability contract |
| Name collision with existing `goggles::compositor` | None | Confirmed: `goggles::compositor` does not exist anywhere in the codebase |

## Rollback Plan

Single commit. Revert the commit to restore `goggles::input` everywhere.

## Dependencies

None. No external consumers, no ABI boundary, no submodule impact.

## Validation Plan

- `pixi run build -p debug` — confirms compilation after rename.
- `pixi run test -p test` — confirms all tests pass with new namespace.
- `pixi run ci --runner container --cache-mode warm --lane all` — full CI gate (ALWAYS rule, I2/I7).

## Success Criteria

- [ ] Zero occurrences of `goggles::input` in `src/` and `tests/` (excluding archived docs).
- [ ] All compositor module files use `namespace goggles::compositor`.
- [ ] The forward declaration in `src/ui/imgui_layer.hpp` references `goggles::compositor`.
- [ ] Full CI passes: `pixi run ci --runner container --cache-mode warm --lane all`.
- [ ] The ALWAYS rule "Follow namespace convention: `goggles::{module_name}`" applies uniformly with no exceptions.

## PROJECT_RULES.md Compliance

| Rule | Status |
|------|--------|
| ALWAYS: Follow namespace convention `goggles::{module_name}` (I3) | This change enforces it |
| ALWAYS: Run `pixi run format` before committing (I7) | Step 4 |
| ALWAYS: Use `pixi run ci ...` for final verification (I2, I7) | Step 4 |
| NEVER: Create circular module dependencies (I8) | No dependency changes |
| NEVER: Modify files in `shaders/retroarch/` or `research/` (I3) | Not touched |
| ASK FIRST: Modifying filter-chain library boundary (I4) | Not touched — confirmed zero impact |
143 changes: 143 additions & 0 deletions openspec/changes/archive/2026-03-19-rename-compositor-namespace/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
# Spec: Rename compositor namespace from goggles::input to goggles::compositor

**Change:** rename-compositor-namespace
**Proposal:** [proposal.md](proposal.md)

---

## Requirement: Namespace Declaration Convention

All source files in the `src/compositor/` directory SHALL declare their namespace as `namespace goggles::compositor`. No file in the compositor module SHALL use `namespace goggles::input` or any other namespace that does not match the directory name.

### Scenario: Compositor headers use correct namespace

- **GIVEN** the compositor public and internal headers:
- `src/compositor/compositor_server.hpp`
- `src/compositor/compositor_state.hpp`
- `src/compositor/compositor_protocol_hooks.hpp`
- `src/compositor/compositor_targets.hpp`
- `src/compositor/compositor_runtime_metrics.hpp`
- **WHEN** namespace declarations in each file are inspected
- **THEN** every namespace declaration SHALL be `namespace goggles::compositor`
- **AND** zero occurrences of `namespace goggles::input` SHALL exist

### Scenario: Compositor implementation files use correct namespace

- **GIVEN** the compositor implementation files:
- `src/compositor/compositor_server.cpp`
- `src/compositor/compositor_core.cpp`
- `src/compositor/compositor_cursor.cpp`
- `src/compositor/compositor_input.cpp`
- `src/compositor/compositor_focus.cpp`
- `src/compositor/compositor_layer_shell.cpp`
- `src/compositor/compositor_present.cpp`
- `src/compositor/compositor_xdg.cpp`
- `src/compositor/compositor_xwayland.cpp`
- **WHEN** namespace declarations in each file are inspected
- **THEN** every namespace declaration SHALL be `namespace goggles::compositor`
- **AND** zero occurrences of `namespace goggles::input` SHALL exist

---

## Requirement: No Residual References to Old Namespace

After the rename, zero occurrences of the string `goggles::input` SHALL exist anywhere in `src/` or `tests/`. This ensures no stale qualified references, using-declarations, or comments referencing the old namespace survive the rename.

### Scenario: Source tree contains no old namespace references

- **GIVEN** the directories `src/` and `tests/`
- **WHEN** a text search for the literal string `goggles::input` is executed across all files
- **THEN** zero matches SHALL be found

### Scenario: No residual using-declarations reference old namespace

- **GIVEN** the directories `src/` and `tests/`
- **WHEN** a text search for `using namespace goggles::input` or `namespace input = goggles::input` is executed
- **THEN** zero matches SHALL be found

---

## Requirement: Forward Declaration Consistency

The forward declaration of compositor types in consumer modules SHALL reference the `goggles::compositor` namespace, not `goggles::input`.

### Scenario: ImGui layer forward declaration updated

- **GIVEN** the file `src/ui/imgui_layer.hpp`
- **WHEN** forward declarations of compositor types are inspected
- **THEN** the forward declaration of `SurfaceInfo` SHALL appear within `namespace goggles::compositor`
- **AND** zero occurrences of `namespace goggles::input` SHALL exist in the file

---

## Requirement: Qualified Reference Consistency in Tests

All test files that reference compositor types via fully qualified names SHALL use the `goggles::compositor::` prefix.

### Scenario: Input forwarding test files use new namespace

- **GIVEN** the test files:
- `tests/input/auto_input_forwarding_wayland.cpp`
- `tests/input/auto_input_forwarding_x11.cpp`
- **WHEN** qualified references to `CompositorServer::create()` are inspected
- **THEN** every reference SHALL use `goggles::compositor::CompositorServer::create()`
- **AND** zero occurrences of `goggles::input::CompositorServer` SHALL exist

### Scenario: Filter boundary contract tests use new namespace

- **GIVEN** the file `tests/render/test_filter_boundary_contracts.cpp`
- **WHEN** qualified references to compositor types are inspected
- **THEN** references to `wlr_surface` and `RuntimeMetricsState` SHALL use the `goggles::compositor::` prefix
- **AND** zero occurrences of `goggles::input::` SHALL exist in the file

---

## Requirement: Build Verification

The project SHALL compile cleanly and pass all tests after the namespace rename. Because the old namespace `goggles::input` ceases to exist, any missed reference will produce a hard compile error — there is no risk of a silent partial rename.

### Scenario: Debug build succeeds

- **GIVEN** all namespace changes are applied
- **WHEN** `pixi run build -p debug` is executed
- **THEN** the build SHALL succeed with zero errors

### Scenario: Full test suite passes

- **GIVEN** all namespace changes are applied
- **WHEN** `pixi run test -p test` is executed
- **THEN** all tests SHALL pass

### Scenario: Full CI pipeline passes

- **GIVEN** all namespace changes are applied and formatted via `pixi run format`
- **WHEN** `pixi run ci --runner container --cache-mode warm --lane all` is executed
- **THEN** all CI lanes SHALL pass (format, build+test with ASAN, package install + consumer validation, semgrep, clang-tidy quality gate)

---

## Requirement: No Functional Changes

The rename SHALL be a purely mechanical transformation. No type names, function signatures, class APIs, or runtime behavior SHALL change. Only the enclosing namespace identifier changes from `input` to `compositor`.

### Scenario: Type names are preserved

- **GIVEN** the compositor module types: `CompositorServer`, `CompositorState`, `SurfaceInfo`, `RuntimeMetricsState`, and all other public and internal types
- **WHEN** their declarations are inspected after the rename
- **THEN** every type name SHALL be identical to its pre-rename name
- **AND** only the enclosing namespace SHALL differ

### Scenario: Function signatures are preserved

- **GIVEN** all public and internal function signatures in the compositor module
- **WHEN** they are inspected after the rename
- **THEN** every function name, parameter list, and return type SHALL be identical to pre-rename
- **AND** no function SHALL be added, removed, or modified

### Scenario: No files created or deleted

- **GIVEN** the set of files modified by this change
- **WHEN** the changeset is inspected
- **THEN** zero files SHALL be created
- **AND** zero files SHALL be deleted
- **AND** exactly 18 files SHALL be modified (14 compositor module files, 1 UI forward declaration, 3 test files)
Comment on lines +137 to +143
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fix contradictory file-change assertions in the spec.

Line 141 and Line 142 conflict with this changeset (this spec file is newly added), and the hardcoded “exactly 18 files” count on Line 143 is brittle for archived documentation.

Proposed spec adjustment 
 ### Scenario: No files created or deleted
-
-- **GIVEN** the set of files modified by this change
-- **WHEN** the changeset is inspected
-- **THEN** zero files SHALL be created
-- **AND** zero files SHALL be deleted
-- **AND** exactly 18 files SHALL be modified (14 compositor module files, 1 UI forward declaration, 3 test files)
+### Scenario: Expected code-scope footprint
+
+- **GIVEN** the namespace-rename implementation scope under `src/` and `tests/`
+- **WHEN** the changeset is inspected
+- **THEN** modifications SHALL be limited to compositor namespace references and related forward declarations/tests
+- **AND** no unrelated functional code changes SHALL be introduced
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@openspec/changes/archive/2026-03-19-rename-compositor-namespace/spec.md`
around lines 137 - 143, The spec currently contains contradictory and brittle
assertions in the "Scenario: No files created or deleted" section: the lines
asserting "zero files SHALL be created" and "zero files SHALL be deleted"
conflict with this spec file being newly added, and the hardcoded "exactly 18
files SHALL be modified" is brittle. Update that scenario by removing or
relaxing the absolute zero-create/zero-delete claims (or explicitly exempt the
new spec file), and replace the hardcoded "exactly 18 files SHALL be modified"
with a non-brittle description (e.g., "the expected set of files for this
changeset are modified" or parameterized count), editing the section title
"Scenario: No files created or deleted" and the three assertions "zero files
SHALL be created", "zero files SHALL be deleted", and "exactly 18 files SHALL be
modified" accordingly so the statements are consistent and no longer rely on a
fragile fixed number.

Loading
Loading