Skip to main content

Decorations Implementation Summary

This document provides a summary of the decorations feature implementation in Morphir.

Overview​

Decorations allow attaching metadata to Morphir IR nodes (types, values, modules) through sidecar files. The decoration schema is defined in Morphir IR itself, ensuring type safety and consistency.

Implementation Status​

✅ Completed Phases​

Phase 1: Core Decoration Infrastructure​

  • ✅ DecorationConfig struct in pkg/config
  • ✅ Support for decorations in morphir.json and morphir.toml
  • ✅ DecorationIR domain type for loaded decoration schemas
  • ✅ DecorationValues domain type for decoration data
  • ✅ IR loading and entry point validation
  • ✅ Decoration value file loading/saving
  • ✅ Type checking for decoration values
  • ✅ Constructor argument validation

Phase 2: IR Integration​

  • ✅ NodePath type for identifying IR nodes
  • ✅ DecorationRegistry for managing attached decorations
  • ✅ AttachedDistribution wrapper combining IR and decorations
  • ✅ LoadAndAttachDecorations function
  • ✅ Query functions for types, values, and modules
  • ✅ Filtering and aggregation functions

Phase 3: CLI Commands​

  • ✅ morphir decoration setup - Configure decorations in project
  • ✅ morphir decoration validate - Validate decoration values
  • ✅ morphir decoration type register/list/show/unregister - Type registry management
  • ✅ morphir decoration list/get/search/stats - Value query commands
  • ✅ JSON output support for all commands
  • ✅ Type registry with workspace/global/system levels

Phase 5: Test Fixtures and Examples​

  • ✅ Example decoration projects (simple-flag, documentation)
  • ✅ Test fixtures in tests/bdd/testdata/decorations/
  • ✅ BDD feature file for decoration loading
  • ✅ Integration test steps for decoration CLI commands

📝 Documentation​

  • ✅ User guide (docs/user-guides/development-guides/decorators-users-guide.md)
  • ✅ CLI reference (docs/reference/decorations/cli-reference.md)
  • ✅ Implementation plan (docs/developers/decorators-implementation-plan.md)
  • ✅ Registry design (docs/developers/decoration-registry-design.md)

🔄 Pending Phases​

Phase 4: API Endpoints​

  • ⏳ Develop server foundation (not yet implemented)
  • ⏳ /server/attributes endpoint
  • ⏳ Decoration CRUD operations API
  • ⏳ Real-time decoration updates

Architecture​

Domain Model​

DecorationConfig (config)
  └─> DecorationIR (tooling/decorations)
       └─> DecorationValues (tooling/decorations)
            └─> DecorationRegistry (models/ir/decorations)
                 └─> AttachedDistribution (tooling/decorations)

Key Components​

  1. Configuration Layer (pkg/config)

    • DecorationConfig: Project-level decoration configuration
    • Supports both morphir.json and morphir.toml

  2. Domain Model (pkg/models/ir/decorations)

    • DecorationIR: Loaded decoration schema
    • DecorationValues: Collection of decoration values
    • DecorationRegistry: Immutable registry of attached decorations
    • NodePath: Unified path for identifying IR nodes

  3. Tooling Layer (pkg/tooling/decorations)

    • IR loading and validation
    • Value file I/O
    • Type checking
    • Attachment logic
    • Query and filtering functions
    • Type registry management

  4. CLI Layer (cmd/morphir/cmd)

    • Setup, validate, query commands
    • Type registry management commands
    • JSON output support

Key Design Decisions​

Immutability​

All data structures are immutable. Operations return new instances rather than modifying existing ones.

NodePath as String Keys​

NodePath contains slices and cannot be used directly as map keys. We use NodePath.String() for map keys, which provides a canonical string representation.

Type Registry Hierarchy​

Decoration types can be registered at three levels:

  1. Workspace: Project-specific (.morphir/decorations/registry.json)
  2. Global: User-wide (~/.morphir/decorations/registry.json)
  3. System: System-wide (/etc/morphir/decorations/registry.json)

Workspace takes precedence over global, which takes precedence over system.

Decoration Attachment​

Decorations are stored separately from the IR distribution, maintaining IR immutability. The AttachedDistribution wrapper provides a unified interface for accessing both.

Usage Examples​

Setting Up a Decoration​

# Using a registered type
morphir decoration setup docs --type documentation

# Using direct paths
morphir decoration setup myDecoration \
  -i decorations/morphir-ir.json \
  -e "My.Decoration:Module:Type"

Registering a Type​

morphir decoration type register documentation \
  -i ~/.morphir/decorations/documentation/morphir-ir.json \
  -e "Documentation.Decoration:Types:Documentation" \
  --display-name "Documentation" \
  --global

Validating Decorations​

morphir decoration validate

Querying Decorations​

# List all decorated nodes
morphir decoration list

# Get decorations for a node
morphir decoration get "My.Package:Foo:bar"

# Show statistics
morphir decoration stats

Testing​

Unit Tests​

  • Configuration parsing (pkg/config/*_test.go)
  • IR loading and validation (pkg/tooling/decorations/*_test.go)
  • Type checking (pkg/tooling/decorations/typecheck*_test.go)
  • Registry operations (pkg/tooling/decorations/type_registry_test.go)
  • Domain model (pkg/models/ir/decorations/*_test.go)

Integration Tests​

  • BDD feature file: tests/bdd/features/decorations/loading.feature
  • CLI command steps: tests/bdd/steps/decoration_steps.go
  • Example projects: examples/decorations/

Future Work​

  1. API Endpoints (Phase 4)

    • Implement develop server
    • Add /server/attributes endpoint
    • Support decoration CRUD operations
    • Real-time updates via WebSocket or polling

  2. Enhanced Search

    • Content-based search in decoration values
    • Full-text search capabilities

  3. Validation Improvements

    • More detailed error messages
    • Validation warnings (non-fatal issues)
    • Batch validation with progress reporting

  4. Performance

    • Caching of loaded decoration IRs
    • Incremental validation
    • Parallel validation for large projects

References​

  • Implementation Plan: docs/developers/decorators-implementation-plan.md
  • Registry Design: docs/developers/decoration-registry-design.md
  • User Guide: docs/user-guides/development-guides/decorators-users-guide.md
  • CLI Reference: docs/reference/decorations/cli-reference.md
  • Examples: examples/decorations/