Developer Tooling Epic

User Journey

The Developer Tooling bounded context provides IDE extensions, LSP server, and CLI tools that enhance the development experience for SEA™ projects. It delivers real-time diagnostics, hover information, code navigation, workspace configuration, and seamless integration with architectural governance and semantic validation.

Jobs to be Done & EARS Requirements

Job: Initialize LSP Server

User Story: As a developer using an IDE, I want to initialize the LSP server, so that I can receive real-time language support for SEA-DSL files.

EARS Requirement:

• While the system is operational, when a StartLSPServer command is received with workspace configuration, the developer-tooling context shall:
  1. Initialize LSP server with workspace path and settings
  2. Load SEA-DSL grammar and syntax highlighting rules
  3. Connect to semantic-core context for validation services
  4. Connect to architectural-governance context for compliance checking
  5. Register capabilities with IDE client:
     • Diagnostics (error/warning/info)
     • Hover information
     • Code completion
     • Go-to-definition
     • Find references
     • Document symbols
  6. Establish file watching for .sea files and related specs
  7. Return server ready status to IDE

Job: Provide Real-Time Diagnostics

User Story: As a developer, I want to see errors and warnings as I type, so that I can fix issues immediately without waiting for build time.

EARS Requirement:

• While editing files, when document content changes, the developer-tooling context shall:
  1. Parse file using appropriate grammar (SEA-DSL, TypeScript, etc.)
  2. Validate semantic correctness via semantic-core context:
     • Syntax errors with line/column positions
     • Type errors and undefined references
     • Policy violations with severity levels
  3. Check architectural compliance via architectural-governance context:
     • Layer boundary violations
     • Dependency rule violations
     • Circular dependency detection
  4. Publish diagnostics to IDE via PublishDiagnostics notification:
     • Error range (start/end position)
     • Severity (error, warning, info, hint)
     • Message with specific issue description
     • Related actions or quick fixes
  5. Ensure deterministic diagnostics (same content produces same results)

Job: Provide Hover Information

User Story: As a developer, I want to see documentation and type information when hovering over code elements, so that I can understand the codebase without navigating away.

EARS Requirement:

• While editing files, when a hover request is received for a position, the developer-tooling context shall:
  1. Identify the symbol or syntax node at the requested position
  2. Retrieve relevant information:
     • Entity definitions (type, properties, constraints)
     • Flow specifications (command/query, source, target)
     • Policy rules (rationale, priority, tags)
     • Documentation comments and related specs
  3. Format hover content with:
     • Symbol name and kind
     • Type signature or definition
     • Documentation from comments or specs
     • Links to related ADRs/PRDs/SDS
  4. Return formatted hover response to IDE client
  5. Handle gracefully when services are unavailable (degraded mode)

Job: Execute CLI Commands

User Story: As a developer, I want to execute commands through the CLI, so that I can perform operations without using the IDE.

EARS Requirement:

• While the system is operational, when an ExecuteCommand request is received with command name and arguments, the developer-tooling context shall:
  1. Parse command and validate arguments
  2. Route to appropriate handler:
     • sea validate: Check SEA-DSL files for errors
     • sea compile: Generate IR and manifest from DSL
     • sea diagram: Generate architecture visualization
     • sea test: Run validation tests
  3. Execute command with appropriate context (workspace, files)
  4. Return output with:
     • Exit code (0 for success, non-zero for failure)
     • Standard output with results
     • Error output with diagnostics
  5. Ensure no secrets are leaked in output
     • Define secrets: API keys, tokens, passwords, connection strings, PII
     • Detect via regex patterns and secret-scanning tools (e.g., git-secrets, truffleHog)
     • Handle by redaction or failing the command with audited logs
     • Allow configurable thresholds and documented false-positive overrides

Job: Configure Workspace Settings

User Story: As a developer, I want to configure workspace settings for the SEA tooling, so that the LSP and CLI behave according to my project’s needs.

EARS Requirement:

• When a workspace configuration is requested or modified, the developer-tooling context shall:
  1. Accept configuration via:
     • sea.json file in workspace root
     • IDE settings extension
     • CLI flags and environment variables
  2. Parse and validate configuration including:
     • Enabled features (diagnostics, completion, validation)
     • Server paths and endpoints
     • Validation rules and severity overrides
     • Output formatting preferences
  3. Apply configuration to LSP server and CLI tools
  4. Persist settings for future sessions
  5. Reload configuration when files change

Job: Enable Code Navigation

User Story: As a developer, I want to navigate to definitions and find references, so that I can explore the codebase efficiently.

EARS Requirement:

• When navigation requests are received, the developer-tooling context shall:
  1. Go-to-Definition:
     • Locate symbol definition in workspace
     • Return file path and line/column position
     • Handle cross-file references in SEA-DSL
  2. Find-References:
     • Search workspace for all symbol usages
     • Return list of locations with file, line, column
     • Include definition and reference types
  3. Document Symbols:
     • Parse document for top-level structures
     • Return hierarchical symbol list (entities, flows, policies)
     • Support outline view and document navigation

Domain Entities Summary

Root Aggregates

• LSPServer: Represents an active Language Server Protocol connection with workspace path, capabilities, and client connection
• DiagnosticReport: Aggregates diagnostics for a document with errors, warnings, and info messages
• WorkspaceConfiguration: Represents tooling settings for a workspace with feature flags, server paths, and preferences

Value Objects

• Diagnostic: Represents a single diagnostic with range, severity, message, and code actions
• HoverContent: Formatted documentation and type information for symbol hover
• SymbolLocation: File path and position (line/column) for code navigation
• CommandResult: Output from CLI execution with exit code, stdout, and stderr

Policy Rules

• DeterministicDiagnostics: Same file content must produce identical diagnostic results
• NoSecretsInOutput: CLI and LSP responses must never include sensitive information
• GracefulDegradation: Tools must function with reduced capabilities when services are unavailable

Integration Points

• Semantic Core Context: Provides SEA-DSL parsing, validation, and semantic information
• Architectural Governance Context: Supplies architectural compliance checks and violations
• IDE Clients: Integrates with VS Code, Zed, Neovim, and other LSP-compatible editors
• CLI Interface: Provides command-line tools for terminal workflows
• File System: Monitors workspace files for changes and hot-reload