61 lines
3.8 KiB
Markdown
61 lines
3.8 KiB
Markdown
# Policy DSL (stella-dsl@1)
|
|
|
|
## Module
|
|
Policy
|
|
|
|
## Status
|
|
IMPLEMENTED
|
|
|
|
## Description
|
|
Policy loading and evaluation exist but the full `.stella` file DSL format with dedicated parser/compiler/simulator (stella policy lint/compile/simulate) was not found as a standalone tool. Policy evaluation is implemented through structured configuration. However, a full DSL parser/compiler exists in the `StellaOps.PolicyDsl` library.
|
|
|
|
## What's Implemented
|
|
- **DslTokenizer**: `src/Policy/StellaOps.PolicyDsl/DslTokenizer.cs`
|
|
- Full lexer with token types: braces, parens, brackets, comma, semicolon, colon, operators
|
|
- Comment support: single-line (`//`) and multi-line (`/* */`)
|
|
- Source location tracking (line, column) for diagnostics
|
|
- `TokenizerResult` with tokens and diagnostics
|
|
- **PolicyParser**: `src/Policy/StellaOps.PolicyDsl/PolicyParser.cs`
|
|
- Parses token stream into `PolicyDocumentNode` AST
|
|
- Metadata, settings, profiles, and rules sections
|
|
- **PolicyCompiler**: `src/Policy/StellaOps.PolicyDsl/PolicyCompiler.cs`
|
|
- `Compile(source)` -> `PolicyCompilationResult` with Success, IR Document, SHA256 Checksum, CanonicalRepresentation, Diagnostics
|
|
- Pipeline: Parse -> Build IR -> Serialize canonical -> Compute SHA256 digest
|
|
- Error collection: any `PolicyIssueSeverity.Error` diagnostic fails compilation
|
|
- **PolicyIr / PolicyIrSerializer**: `src/Policy/StellaOps.PolicyDsl/PolicyIr.cs`, `PolicyIrSerializer.cs`
|
|
- Intermediate representation: PolicyIrDocument, PolicyIrProfile (maps, envs, scalars), PolicyIrRule
|
|
- Canonical binary serialization for digest computation
|
|
- **PolicySyntaxNodes**: `src/Policy/StellaOps.PolicyDsl/PolicySyntaxNodes.cs`
|
|
- AST node types for the DSL grammar
|
|
- **DslCompletionProvider**: `src/Policy/StellaOps.PolicyDsl/DslCompletionProvider.cs`
|
|
- IDE-style completion suggestions for the DSL
|
|
- **SignalContext**: `src/Policy/StellaOps.PolicyDsl/SignalContext.cs`
|
|
- Runtime signal value provider: HasSignal, GetSignal<T>, SetSignal
|
|
- Extension methods: `SecretSignalContextExtensions.cs`, `AiCodeGuardSignalContextExtensions.cs`
|
|
- **PolicyEngineFactory**: `src/Policy/StellaOps.PolicyDsl/PolicyEngineFactory.cs`
|
|
- Factory for creating policy evaluation engines from compiled DSL
|
|
- **DiagnosticCodes**: `src/Policy/StellaOps.PolicyDsl/DiagnosticCodes.cs`
|
|
- Structured diagnostic codes for parser/compiler errors
|
|
- **SourceLocation**: `src/Policy/StellaOps.PolicyDsl/SourceLocation.cs`
|
|
- Position tracking (offset, line, column) for error reporting
|
|
- **Tests**: `src/Policy/__Tests/StellaOps.PolicyDsl.Tests/` (7 test files)
|
|
- PolicyCompilerTests, PolicyEngineTests, SignalContextTests, DslCompletionProviderTests
|
|
|
|
## What's Missing
|
|
- **CLI commands**: No `stella policy lint`, `stella policy compile`, or `stella policy simulate` CLI commands wrapping the DSL library
|
|
- **`.stella` file format specification**: No formal grammar specification or documentation of the DSL syntax
|
|
- **Policy simulation with DSL**: The `PolicySimulationEngine` in the policy engine does not integrate with DSL-compiled policies
|
|
- **DSL-to-PolicyPack bridge**: No converter from compiled DSL IR to the PolicyPackDocument format used by the interop framework
|
|
- **Language server protocol (LSP)**: DslCompletionProvider exists but no LSP server for editor integration
|
|
|
|
## Implementation Plan
|
|
- Add CLI commands (`stella policy lint/compile/simulate`) that wrap the PolicyDsl library
|
|
- Create DSL grammar specification document
|
|
- Build bridge from compiled PolicyIrDocument to PolicyPackDocument for interop
|
|
- Integrate DSL compilation into the policy bundle build pipeline
|
|
|
|
## Related Documentation
|
|
- PolicyDsl library: `src/Policy/StellaOps.PolicyDsl/` (16 source files)
|
|
- PolicyDsl tests: `src/Policy/__Tests/StellaOps.PolicyDsl.Tests/`
|
|
- Policy interop: `src/Policy/__Libraries/StellaOps.Policy.Interop/`
|